Edit on GitHub

Expressions

Every AST node in SQLGlot is represented by a subclass of Expression.

This module contains the implementation of all supported Expression types. Additionally, it exposes a number of helper functions, which are mainly used to programmatically build SQL expressions, such as sqlglot.expressions.select.


   1"""
   2## Expressions
   3
   4Every AST node in SQLGlot is represented by a subclass of `Expression`.
   5
   6This module contains the implementation of all supported `Expression` types. Additionally,
   7it exposes a number of helper functions, which are mainly used to programmatically build
   8SQL expressions, such as `sqlglot.expressions.select`.
   9
  10----
  11"""
  12
  13from __future__ import annotations
  14
  15import datetime
  16import math
  17import numbers
  18import re
  19import typing as t
  20from collections import deque
  21from copy import deepcopy
  22from enum import auto
  23
  24from sqlglot.errors import ParseError
  25from sqlglot.helper import (
  26    AutoName,
  27    camel_to_snake_case,
  28    ensure_collection,
  29    seq_get,
  30    split_num_words,
  31    subclasses,
  32)
  33from sqlglot.tokens import Token
  34
  35if t.TYPE_CHECKING:
  36    from sqlglot.dialects.dialect import DialectType
  37
  38E = t.TypeVar("E", bound="Expression")
  39
  40
  41class _Expression(type):
  42    def __new__(cls, clsname, bases, attrs):
  43        klass = super().__new__(cls, clsname, bases, attrs)
  44
  45        # When an Expression class is created, its key is automatically set to be
  46        # the lowercase version of the class' name.
  47        klass.key = clsname.lower()
  48
  49        # This is so that docstrings are not inherited in pdoc
  50        klass.__doc__ = klass.__doc__ or ""
  51
  52        return klass
  53
  54
  55class Expression(metaclass=_Expression):
  56    """
  57    The base class for all expressions in a syntax tree. Each Expression encapsulates any necessary
  58    context, such as its child expressions, their names (arg keys), and whether a given child expression
  59    is optional or not.
  60
  61    Attributes:
  62        key: a unique key for each class in the Expression hierarchy. This is useful for hashing
  63            and representing expressions as strings.
  64        arg_types: determines what arguments (child nodes) are supported by an expression. It
  65            maps arg keys to booleans that indicate whether the corresponding args are optional.
  66
  67    Example:
  68        >>> class Foo(Expression):
  69        ...     arg_types = {"this": True, "expression": False}
  70
  71        The above definition informs us that Foo is an Expression that requires an argument called
  72        "this" and may also optionally receive an argument called "expression".
  73
  74    Args:
  75        args: a mapping used for retrieving the arguments of an expression, given their arg keys.
  76        parent: a reference to the parent expression (or None, in case of root expressions).
  77        arg_key: the arg key an expression is associated with, i.e. the name its parent expression
  78            uses to refer to it.
  79        comments: a list of comments that are associated with a given expression. This is used in
  80            order to preserve comments when transpiling SQL code.
  81        _type: the `sqlglot.expressions.DataType` type of an expression. This is inferred by the
  82            optimizer, in order to enable some transformations that require type information.
  83    """
  84
  85    key = "expression"
  86    arg_types = {"this": True}
  87    __slots__ = ("args", "parent", "arg_key", "comments", "_type", "_meta")
  88
  89    def __init__(self, **args: t.Any):
  90        self.args: t.Dict[str, t.Any] = args
  91        self.parent: t.Optional[Expression] = None
  92        self.arg_key: t.Optional[str] = None
  93        self.comments: t.Optional[t.List[str]] = None
  94        self._type: t.Optional[DataType] = None
  95        self._meta: t.Optional[t.Dict[str, t.Any]] = None
  96
  97        for arg_key, value in self.args.items():
  98            self._set_parent(arg_key, value)
  99
 100    def __eq__(self, other) -> bool:
 101        return type(self) is type(other) and _norm_args(self) == _norm_args(other)
 102
 103    def __hash__(self) -> int:
 104        return hash(
 105            (
 106                self.key,
 107                tuple(
 108                    (k, tuple(v) if isinstance(v, list) else v) for k, v in _norm_args(self).items()
 109                ),
 110            )
 111        )
 112
 113    @property
 114    def this(self):
 115        """
 116        Retrieves the argument with key "this".
 117        """
 118        return self.args.get("this")
 119
 120    @property
 121    def expression(self):
 122        """
 123        Retrieves the argument with key "expression".
 124        """
 125        return self.args.get("expression")
 126
 127    @property
 128    def expressions(self):
 129        """
 130        Retrieves the argument with key "expressions".
 131        """
 132        return self.args.get("expressions") or []
 133
 134    def text(self, key) -> str:
 135        """
 136        Returns a textual representation of the argument corresponding to "key". This can only be used
 137        for args that are strings or leaf Expression instances, such as identifiers and literals.
 138        """
 139        field = self.args.get(key)
 140        if isinstance(field, str):
 141            return field
 142        if isinstance(field, (Identifier, Literal, Var)):
 143            return field.this
 144        if isinstance(field, (Star, Null)):
 145            return field.name
 146        return ""
 147
 148    @property
 149    def is_string(self) -> bool:
 150        """
 151        Checks whether a Literal expression is a string.
 152        """
 153        return isinstance(self, Literal) and self.args["is_string"]
 154
 155    @property
 156    def is_number(self) -> bool:
 157        """
 158        Checks whether a Literal expression is a number.
 159        """
 160        return isinstance(self, Literal) and not self.args["is_string"]
 161
 162    @property
 163    def is_int(self) -> bool:
 164        """
 165        Checks whether a Literal expression is an integer.
 166        """
 167        if self.is_number:
 168            try:
 169                int(self.name)
 170                return True
 171            except ValueError:
 172                pass
 173        return False
 174
 175    @property
 176    def is_star(self) -> bool:
 177        """Checks whether an expression is a star."""
 178        return isinstance(self, Star) or (isinstance(self, Column) and isinstance(self.this, Star))
 179
 180    @property
 181    def alias(self) -> str:
 182        """
 183        Returns the alias of the expression, or an empty string if it's not aliased.
 184        """
 185        if isinstance(self.args.get("alias"), TableAlias):
 186            return self.args["alias"].name
 187        return self.text("alias")
 188
 189    @property
 190    def name(self) -> str:
 191        return self.text("this")
 192
 193    @property
 194    def alias_or_name(self):
 195        return self.alias or self.name
 196
 197    @property
 198    def output_name(self):
 199        """
 200        Name of the output column if this expression is a selection.
 201
 202        If the Expression has no output name, an empty string is returned.
 203
 204        Example:
 205            >>> from sqlglot import parse_one
 206            >>> parse_one("SELECT a").expressions[0].output_name
 207            'a'
 208            >>> parse_one("SELECT b AS c").expressions[0].output_name
 209            'c'
 210            >>> parse_one("SELECT 1 + 2").expressions[0].output_name
 211            ''
 212        """
 213        return ""
 214
 215    @property
 216    def type(self) -> t.Optional[DataType]:
 217        return self._type
 218
 219    @type.setter
 220    def type(self, dtype: t.Optional[DataType | DataType.Type | str]) -> None:
 221        if dtype and not isinstance(dtype, DataType):
 222            dtype = DataType.build(dtype)
 223        self._type = dtype  # type: ignore
 224
 225    @property
 226    def meta(self) -> t.Dict[str, t.Any]:
 227        if self._meta is None:
 228            self._meta = {}
 229        return self._meta
 230
 231    def __deepcopy__(self, memo):
 232        copy = self.__class__(**deepcopy(self.args))
 233        if self.comments is not None:
 234            copy.comments = deepcopy(self.comments)
 235
 236        if self._type is not None:
 237            copy._type = self._type.copy()
 238
 239        if self._meta is not None:
 240            copy._meta = deepcopy(self._meta)
 241
 242        return copy
 243
 244    def copy(self):
 245        """
 246        Returns a deep copy of the expression.
 247        """
 248        new = deepcopy(self)
 249        new.parent = self.parent
 250        for item, parent, _ in new.bfs():
 251            if isinstance(item, Expression) and parent:
 252                item.parent = parent
 253        return new
 254
 255    def append(self, arg_key, value):
 256        """
 257        Appends value to arg_key if it's a list or sets it as a new list.
 258
 259        Args:
 260            arg_key (str): name of the list expression arg
 261            value (Any): value to append to the list
 262        """
 263        if not isinstance(self.args.get(arg_key), list):
 264            self.args[arg_key] = []
 265        self.args[arg_key].append(value)
 266        self._set_parent(arg_key, value)
 267
 268    def set(self, arg_key, value):
 269        """
 270        Sets `arg_key` to `value`.
 271
 272        Args:
 273            arg_key (str): name of the expression arg.
 274            value: value to set the arg to.
 275        """
 276        self.args[arg_key] = value
 277        self._set_parent(arg_key, value)
 278
 279    def _set_parent(self, arg_key, value):
 280        if isinstance(value, Expression):
 281            value.parent = self
 282            value.arg_key = arg_key
 283        elif isinstance(value, list):
 284            for v in value:
 285                if isinstance(v, Expression):
 286                    v.parent = self
 287                    v.arg_key = arg_key
 288
 289    @property
 290    def depth(self):
 291        """
 292        Returns the depth of this tree.
 293        """
 294        if self.parent:
 295            return self.parent.depth + 1
 296        return 0
 297
 298    def find(self, *expression_types: t.Type[E], bfs=True) -> E | None:
 299        """
 300        Returns the first node in this tree which matches at least one of
 301        the specified types.
 302
 303        Args:
 304            expression_types (type): the expression type(s) to match.
 305
 306        Returns:
 307            The node which matches the criteria or None if no such node was found.
 308        """
 309        return next(self.find_all(*expression_types, bfs=bfs), None)
 310
 311    def find_all(self, *expression_types: t.Type[E], bfs=True) -> t.Iterator[E]:
 312        """
 313        Returns a generator object which visits all nodes in this tree and only
 314        yields those that match at least one of the specified expression types.
 315
 316        Args:
 317            expression_types (type): the expression type(s) to match.
 318
 319        Returns:
 320            The generator object.
 321        """
 322        for expression, _, _ in self.walk(bfs=bfs):
 323            if isinstance(expression, expression_types):
 324                yield expression
 325
 326    def find_ancestor(self, *expression_types: t.Type[E]) -> E | None:
 327        """
 328        Returns a nearest parent matching expression_types.
 329
 330        Args:
 331            expression_types (type): the expression type(s) to match.
 332
 333        Returns:
 334            The parent node.
 335        """
 336        ancestor = self.parent
 337        while ancestor and not isinstance(ancestor, expression_types):
 338            ancestor = ancestor.parent
 339        # ignore type because mypy doesn't know that we're checking type in the loop
 340        return ancestor  # type: ignore[return-value]
 341
 342    @property
 343    def parent_select(self):
 344        """
 345        Returns the parent select statement.
 346        """
 347        return self.find_ancestor(Select)
 348
 349    def root(self) -> Expression:
 350        """
 351        Returns the root expression of this tree.
 352        """
 353        expression = self
 354        while expression.parent:
 355            expression = expression.parent
 356        return expression
 357
 358    def walk(self, bfs=True, prune=None):
 359        """
 360        Returns a generator object which visits all nodes in this tree.
 361
 362        Args:
 363            bfs (bool): if set to True the BFS traversal order will be applied,
 364                otherwise the DFS traversal will be used instead.
 365            prune ((node, parent, arg_key) -> bool): callable that returns True if
 366                the generator should stop traversing this branch of the tree.
 367
 368        Returns:
 369            the generator object.
 370        """
 371        if bfs:
 372            yield from self.bfs(prune=prune)
 373        else:
 374            yield from self.dfs(prune=prune)
 375
 376    def dfs(self, parent=None, key=None, prune=None):
 377        """
 378        Returns a generator object which visits all nodes in this tree in
 379        the DFS (Depth-first) order.
 380
 381        Returns:
 382            The generator object.
 383        """
 384        parent = parent or self.parent
 385        yield self, parent, key
 386        if prune and prune(self, parent, key):
 387            return
 388
 389        for k, v in self.args.items():
 390            for node in ensure_collection(v):
 391                if isinstance(node, Expression):
 392                    yield from node.dfs(self, k, prune)
 393
 394    def bfs(self, prune=None):
 395        """
 396        Returns a generator object which visits all nodes in this tree in
 397        the BFS (Breadth-first) order.
 398
 399        Returns:
 400            The generator object.
 401        """
 402        queue = deque([(self, self.parent, None)])
 403
 404        while queue:
 405            item, parent, key = queue.popleft()
 406
 407            yield item, parent, key
 408            if prune and prune(item, parent, key):
 409                continue
 410
 411            if isinstance(item, Expression):
 412                for k, v in item.args.items():
 413                    for node in ensure_collection(v):
 414                        if isinstance(node, Expression):
 415                            queue.append((node, item, k))
 416
 417    def unnest(self):
 418        """
 419        Returns the first non parenthesis child or self.
 420        """
 421        expression = self
 422        while isinstance(expression, Paren):
 423            expression = expression.this
 424        return expression
 425
 426    def unalias(self):
 427        """
 428        Returns the inner expression if this is an Alias.
 429        """
 430        if isinstance(self, Alias):
 431            return self.this
 432        return self
 433
 434    def unnest_operands(self):
 435        """
 436        Returns unnested operands as a tuple.
 437        """
 438        return tuple(arg.unnest() for arg in self.args.values() if arg)
 439
 440    def flatten(self, unnest=True):
 441        """
 442        Returns a generator which yields child nodes who's parents are the same class.
 443
 444        A AND B AND C -> [A, B, C]
 445        """
 446        for node, _, _ in self.dfs(prune=lambda n, p, *_: p and not isinstance(n, self.__class__)):
 447            if not isinstance(node, self.__class__):
 448                yield node.unnest() if unnest else node
 449
 450    def __str__(self):
 451        return self.sql()
 452
 453    def __repr__(self):
 454        return self._to_s()
 455
 456    def sql(self, dialect: DialectType = None, **opts) -> str:
 457        """
 458        Returns SQL string representation of this tree.
 459
 460        Args:
 461            dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql").
 462            opts: other `sqlglot.generator.Generator` options.
 463
 464        Returns:
 465            The SQL string.
 466        """
 467        from sqlglot.dialects import Dialect
 468
 469        return Dialect.get_or_raise(dialect)().generate(self, **opts)
 470
 471    def _to_s(self, hide_missing: bool = True, level: int = 0) -> str:
 472        indent = "" if not level else "\n"
 473        indent += "".join(["  "] * level)
 474        left = f"({self.key.upper()} "
 475
 476        args: t.Dict[str, t.Any] = {
 477            k: ", ".join(
 478                v._to_s(hide_missing=hide_missing, level=level + 1)
 479                if hasattr(v, "_to_s")
 480                else str(v)
 481                for v in ensure_collection(vs)
 482                if v is not None
 483            )
 484            for k, vs in self.args.items()
 485        }
 486        args["comments"] = self.comments
 487        args["type"] = self.type
 488        args = {k: v for k, v in args.items() if v or not hide_missing}
 489
 490        right = ", ".join(f"{k}: {v}" for k, v in args.items())
 491        right += ")"
 492
 493        return indent + left + right
 494
 495    def transform(self, fun, *args, copy=True, **kwargs):
 496        """
 497        Recursively visits all tree nodes (excluding already transformed ones)
 498        and applies the given transformation function to each node.
 499
 500        Args:
 501            fun (function): a function which takes a node as an argument and returns a
 502                new transformed node or the same node without modifications. If the function
 503                returns None, then the corresponding node will be removed from the syntax tree.
 504            copy (bool): if set to True a new tree instance is constructed, otherwise the tree is
 505                modified in place.
 506
 507        Returns:
 508            The transformed tree.
 509        """
 510        node = self.copy() if copy else self
 511        new_node = fun(node, *args, **kwargs)
 512
 513        if new_node is None or not isinstance(new_node, Expression):
 514            return new_node
 515        if new_node is not node:
 516            new_node.parent = node.parent
 517            return new_node
 518
 519        replace_children(new_node, lambda child: child.transform(fun, *args, copy=False, **kwargs))
 520        return new_node
 521
 522    def replace(self, expression):
 523        """
 524        Swap out this expression with a new expression.
 525
 526        For example::
 527
 528            >>> tree = Select().select("x").from_("tbl")
 529            >>> tree.find(Column).replace(Column(this="y"))
 530            (COLUMN this: y)
 531            >>> tree.sql()
 532            'SELECT y FROM tbl'
 533
 534        Args:
 535            expression (Expression|None): new node
 536
 537        Returns:
 538            The new expression or expressions.
 539        """
 540        if not self.parent:
 541            return expression
 542
 543        parent = self.parent
 544        self.parent = None
 545
 546        replace_children(parent, lambda child: expression if child is self else child)
 547        return expression
 548
 549    def pop(self):
 550        """
 551        Remove this expression from its AST.
 552        """
 553        self.replace(None)
 554
 555    def assert_is(self, type_):
 556        """
 557        Assert that this `Expression` is an instance of `type_`.
 558
 559        If it is NOT an instance of `type_`, this raises an assertion error.
 560        Otherwise, this returns this expression.
 561
 562        Examples:
 563            This is useful for type security in chained expressions:
 564
 565            >>> import sqlglot
 566            >>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql()
 567            'SELECT x, z FROM y'
 568        """
 569        assert isinstance(self, type_)
 570        return self
 571
 572    def error_messages(self, args: t.Optional[t.Sequence] = None) -> t.List[str]:
 573        """
 574        Checks if this expression is valid (e.g. all mandatory args are set).
 575
 576        Args:
 577            args: a sequence of values that were used to instantiate a Func expression. This is used
 578                to check that the provided arguments don't exceed the function argument limit.
 579
 580        Returns:
 581            A list of error messages for all possible errors that were found.
 582        """
 583        errors: t.List[str] = []
 584
 585        for k in self.args:
 586            if k not in self.arg_types:
 587                errors.append(f"Unexpected keyword: '{k}' for {self.__class__}")
 588        for k, mandatory in self.arg_types.items():
 589            v = self.args.get(k)
 590            if mandatory and (v is None or (isinstance(v, list) and not v)):
 591                errors.append(f"Required keyword: '{k}' missing for {self.__class__}")
 592
 593        if (
 594            args
 595            and isinstance(self, Func)
 596            and len(args) > len(self.arg_types)
 597            and not self.is_var_len_args
 598        ):
 599            errors.append(
 600                f"The number of provided arguments ({len(args)}) is greater than "
 601                f"the maximum number of supported arguments ({len(self.arg_types)})"
 602            )
 603
 604        return errors
 605
 606    def dump(self):
 607        """
 608        Dump this Expression to a JSON-serializable dict.
 609        """
 610        from sqlglot.serde import dump
 611
 612        return dump(self)
 613
 614    @classmethod
 615    def load(cls, obj):
 616        """
 617        Load a dict (as returned by `Expression.dump`) into an Expression instance.
 618        """
 619        from sqlglot.serde import load
 620
 621        return load(obj)
 622
 623
 624IntoType = t.Union[
 625    str,
 626    t.Type[Expression],
 627    t.Collection[t.Union[str, t.Type[Expression]]],
 628]
 629
 630
 631class Condition(Expression):
 632    def and_(self, *expressions, dialect=None, **opts):
 633        """
 634        AND this condition with one or multiple expressions.
 635
 636        Example:
 637            >>> condition("x=1").and_("y=1").sql()
 638            'x = 1 AND y = 1'
 639
 640        Args:
 641            *expressions (str | Expression): the SQL code strings to parse.
 642                If an `Expression` instance is passed, it will be used as-is.
 643            dialect (str): the dialect used to parse the input expression.
 644            opts (kwargs): other options to use to parse the input expressions.
 645
 646        Returns:
 647            And: the new condition.
 648        """
 649        return and_(self, *expressions, dialect=dialect, **opts)
 650
 651    def or_(self, *expressions, dialect=None, **opts):
 652        """
 653        OR this condition with one or multiple expressions.
 654
 655        Example:
 656            >>> condition("x=1").or_("y=1").sql()
 657            'x = 1 OR y = 1'
 658
 659        Args:
 660            *expressions (str | Expression): the SQL code strings to parse.
 661                If an `Expression` instance is passed, it will be used as-is.
 662            dialect (str): the dialect used to parse the input expression.
 663            opts (kwargs): other options to use to parse the input expressions.
 664
 665        Returns:
 666            Or: the new condition.
 667        """
 668        return or_(self, *expressions, dialect=dialect, **opts)
 669
 670    def not_(self):
 671        """
 672        Wrap this condition with NOT.
 673
 674        Example:
 675            >>> condition("x=1").not_().sql()
 676            'NOT x = 1'
 677
 678        Returns:
 679            Not: the new condition.
 680        """
 681        return not_(self)
 682
 683
 684class Predicate(Condition):
 685    """Relationships like x = y, x > 1, x >= y."""
 686
 687
 688class DerivedTable(Expression):
 689    @property
 690    def alias_column_names(self):
 691        table_alias = self.args.get("alias")
 692        if not table_alias:
 693            return []
 694        column_list = table_alias.assert_is(TableAlias).args.get("columns") or []
 695        return [c.name for c in column_list]
 696
 697    @property
 698    def selects(self):
 699        alias = self.args.get("alias")
 700
 701        if alias:
 702            return alias.columns
 703        return []
 704
 705    @property
 706    def named_selects(self):
 707        return [select.output_name for select in self.selects]
 708
 709
 710class Unionable(Expression):
 711    def union(self, expression, distinct=True, dialect=None, **opts):
 712        """
 713        Builds a UNION expression.
 714
 715        Example:
 716            >>> import sqlglot
 717            >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql()
 718            'SELECT * FROM foo UNION SELECT * FROM bla'
 719
 720        Args:
 721            expression (str | Expression): the SQL code string.
 722                If an `Expression` instance is passed, it will be used as-is.
 723            distinct (bool): set the DISTINCT flag if and only if this is true.
 724            dialect (str): the dialect used to parse the input expression.
 725            opts (kwargs): other options to use to parse the input expressions.
 726        Returns:
 727            Union: the Union expression.
 728        """
 729        return union(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
 730
 731    def intersect(self, expression, distinct=True, dialect=None, **opts):
 732        """
 733        Builds an INTERSECT expression.
 734
 735        Example:
 736            >>> import sqlglot
 737            >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql()
 738            'SELECT * FROM foo INTERSECT SELECT * FROM bla'
 739
 740        Args:
 741            expression (str | Expression): the SQL code string.
 742                If an `Expression` instance is passed, it will be used as-is.
 743            distinct (bool): set the DISTINCT flag if and only if this is true.
 744            dialect (str): the dialect used to parse the input expression.
 745            opts (kwargs): other options to use to parse the input expressions.
 746        Returns:
 747            Intersect: the Intersect expression
 748        """
 749        return intersect(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
 750
 751    def except_(self, expression, distinct=True, dialect=None, **opts):
 752        """
 753        Builds an EXCEPT expression.
 754
 755        Example:
 756            >>> import sqlglot
 757            >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql()
 758            'SELECT * FROM foo EXCEPT SELECT * FROM bla'
 759
 760        Args:
 761            expression (str | Expression): the SQL code string.
 762                If an `Expression` instance is passed, it will be used as-is.
 763            distinct (bool): set the DISTINCT flag if and only if this is true.
 764            dialect (str): the dialect used to parse the input expression.
 765            opts (kwargs): other options to use to parse the input expressions.
 766        Returns:
 767            Except: the Except expression
 768        """
 769        return except_(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
 770
 771
 772class UDTF(DerivedTable, Unionable):
 773    pass
 774
 775
 776class Cache(Expression):
 777    arg_types = {
 778        "with": False,
 779        "this": True,
 780        "lazy": False,
 781        "options": False,
 782        "expression": False,
 783    }
 784
 785
 786class Uncache(Expression):
 787    arg_types = {"this": True, "exists": False}
 788
 789
 790class Create(Expression):
 791    arg_types = {
 792        "with": False,
 793        "this": True,
 794        "kind": True,
 795        "expression": False,
 796        "exists": False,
 797        "properties": False,
 798        "replace": False,
 799        "unique": False,
 800        "volatile": False,
 801        "indexes": False,
 802        "no_schema_binding": False,
 803        "begin": False,
 804    }
 805
 806
 807class Describe(Expression):
 808    arg_types = {"this": True, "kind": False}
 809
 810
 811class Set(Expression):
 812    arg_types = {"expressions": True}
 813
 814
 815class SetItem(Expression):
 816    arg_types = {
 817        "this": False,
 818        "expressions": False,
 819        "kind": False,
 820        "collate": False,  # MySQL SET NAMES statement
 821        "global": False,
 822    }
 823
 824
 825class Show(Expression):
 826    arg_types = {
 827        "this": True,
 828        "target": False,
 829        "offset": False,
 830        "limit": False,
 831        "like": False,
 832        "where": False,
 833        "db": False,
 834        "full": False,
 835        "mutex": False,
 836        "query": False,
 837        "channel": False,
 838        "global": False,
 839        "log": False,
 840        "position": False,
 841        "types": False,
 842    }
 843
 844
 845class UserDefinedFunction(Expression):
 846    arg_types = {"this": True, "expressions": False, "wrapped": False}
 847
 848
 849class CharacterSet(Expression):
 850    arg_types = {"this": True, "default": False}
 851
 852
 853class With(Expression):
 854    arg_types = {"expressions": True, "recursive": False}
 855
 856    @property
 857    def recursive(self) -> bool:
 858        return bool(self.args.get("recursive"))
 859
 860
 861class WithinGroup(Expression):
 862    arg_types = {"this": True, "expression": False}
 863
 864
 865class CTE(DerivedTable):
 866    arg_types = {"this": True, "alias": True}
 867
 868
 869class TableAlias(Expression):
 870    arg_types = {"this": False, "columns": False}
 871
 872    @property
 873    def columns(self):
 874        return self.args.get("columns") or []
 875
 876
 877class BitString(Condition):
 878    pass
 879
 880
 881class HexString(Condition):
 882    pass
 883
 884
 885class ByteString(Condition):
 886    pass
 887
 888
 889class Column(Condition):
 890    arg_types = {"this": True, "table": False, "db": False, "catalog": False, "join_mark": False}
 891
 892    @property
 893    def table(self) -> str:
 894        return self.text("table")
 895
 896    @property
 897    def db(self) -> str:
 898        return self.text("db")
 899
 900    @property
 901    def catalog(self) -> str:
 902        return self.text("catalog")
 903
 904    @property
 905    def output_name(self) -> str:
 906        return self.name
 907
 908
 909class ColumnDef(Expression):
 910    arg_types = {
 911        "this": True,
 912        "kind": False,
 913        "constraints": False,
 914        "exists": False,
 915    }
 916
 917
 918class AlterColumn(Expression):
 919    arg_types = {
 920        "this": True,
 921        "dtype": False,
 922        "collate": False,
 923        "using": False,
 924        "default": False,
 925        "drop": False,
 926    }
 927
 928
 929class RenameTable(Expression):
 930    pass
 931
 932
 933class SetTag(Expression):
 934    arg_types = {"expressions": True, "unset": False}
 935
 936
 937class ColumnConstraint(Expression):
 938    arg_types = {"this": False, "kind": True}
 939
 940
 941class ColumnConstraintKind(Expression):
 942    pass
 943
 944
 945class AutoIncrementColumnConstraint(ColumnConstraintKind):
 946    pass
 947
 948
 949class CaseSpecificColumnConstraint(ColumnConstraintKind):
 950    arg_types = {"not_": True}
 951
 952
 953class CharacterSetColumnConstraint(ColumnConstraintKind):
 954    arg_types = {"this": True}
 955
 956
 957class CheckColumnConstraint(ColumnConstraintKind):
 958    pass
 959
 960
 961class CollateColumnConstraint(ColumnConstraintKind):
 962    pass
 963
 964
 965class CommentColumnConstraint(ColumnConstraintKind):
 966    pass
 967
 968
 969class CompressColumnConstraint(ColumnConstraintKind):
 970    pass
 971
 972
 973class DateFormatColumnConstraint(ColumnConstraintKind):
 974    arg_types = {"this": True}
 975
 976
 977class DefaultColumnConstraint(ColumnConstraintKind):
 978    pass
 979
 980
 981class EncodeColumnConstraint(ColumnConstraintKind):
 982    pass
 983
 984
 985class GeneratedAsIdentityColumnConstraint(ColumnConstraintKind):
 986    # this: True -> ALWAYS, this: False -> BY DEFAULT
 987    arg_types = {
 988        "this": False,
 989        "start": False,
 990        "increment": False,
 991        "minvalue": False,
 992        "maxvalue": False,
 993        "cycle": False,
 994    }
 995
 996
 997class InlineLengthColumnConstraint(ColumnConstraintKind):
 998    pass
 999
1000
1001class NotNullColumnConstraint(ColumnConstraintKind):
1002    arg_types = {"allow_null": False}
1003
1004
1005class PrimaryKeyColumnConstraint(ColumnConstraintKind):
1006    arg_types = {"desc": False}
1007
1008
1009class TitleColumnConstraint(ColumnConstraintKind):
1010    pass
1011
1012
1013class UniqueColumnConstraint(ColumnConstraintKind):
1014    arg_types: t.Dict[str, t.Any] = {}
1015
1016
1017class UppercaseColumnConstraint(ColumnConstraintKind):
1018    arg_types: t.Dict[str, t.Any] = {}
1019
1020
1021class PathColumnConstraint(ColumnConstraintKind):
1022    pass
1023
1024
1025class Constraint(Expression):
1026    arg_types = {"this": True, "expressions": True}
1027
1028
1029class Delete(Expression):
1030    arg_types = {"with": False, "this": False, "using": False, "where": False}
1031
1032
1033class Drop(Expression):
1034    arg_types = {
1035        "this": False,
1036        "kind": False,
1037        "exists": False,
1038        "temporary": False,
1039        "materialized": False,
1040        "cascade": False,
1041    }
1042
1043
1044class Filter(Expression):
1045    arg_types = {"this": True, "expression": True}
1046
1047
1048class Check(Expression):
1049    pass
1050
1051
1052class Directory(Expression):
1053    # https://spark.apache.org/docs/3.0.0-preview/sql-ref-syntax-dml-insert-overwrite-directory-hive.html
1054    arg_types = {"this": True, "local": False, "row_format": False}
1055
1056
1057class ForeignKey(Expression):
1058    arg_types = {
1059        "expressions": True,
1060        "reference": False,
1061        "delete": False,
1062        "update": False,
1063    }
1064
1065
1066class PrimaryKey(Expression):
1067    arg_types = {"expressions": True, "options": False}
1068
1069
1070class Unique(Expression):
1071    arg_types = {"expressions": True}
1072
1073
1074# https://www.postgresql.org/docs/9.1/sql-selectinto.html
1075# https://docs.aws.amazon.com/redshift/latest/dg/r_SELECT_INTO.html#r_SELECT_INTO-examples
1076class Into(Expression):
1077    arg_types = {"this": True, "temporary": False, "unlogged": False}
1078
1079
1080class From(Expression):
1081    arg_types = {"expressions": True}
1082
1083
1084class Having(Expression):
1085    pass
1086
1087
1088class Hint(Expression):
1089    arg_types = {"expressions": True}
1090
1091
1092class JoinHint(Expression):
1093    arg_types = {"this": True, "expressions": True}
1094
1095
1096class Identifier(Expression):
1097    arg_types = {"this": True, "quoted": False}
1098
1099    @property
1100    def quoted(self):
1101        return bool(self.args.get("quoted"))
1102
1103    def __eq__(self, other):
1104        return isinstance(other, self.__class__) and _norm_arg(self.this) == _norm_arg(other.this)
1105
1106    def __hash__(self):
1107        return hash((self.key, self.this.lower()))
1108
1109    @property
1110    def output_name(self):
1111        return self.name
1112
1113
1114class Index(Expression):
1115    arg_types = {
1116        "this": False,
1117        "table": False,
1118        "where": False,
1119        "columns": False,
1120        "unique": False,
1121        "primary": False,
1122        "amp": False,  # teradata
1123    }
1124
1125
1126class Insert(Expression):
1127    arg_types = {
1128        "with": False,
1129        "this": True,
1130        "expression": False,
1131        "overwrite": False,
1132        "exists": False,
1133        "partition": False,
1134        "alternative": False,
1135    }
1136
1137
1138# https://dev.mysql.com/doc/refman/8.0/en/charset-introducer.html
1139class Introducer(Expression):
1140    arg_types = {"this": True, "expression": True}
1141
1142
1143# national char, like n'utf8'
1144class National(Expression):
1145    pass
1146
1147
1148class LoadData(Expression):
1149    arg_types = {
1150        "this": True,
1151        "local": False,
1152        "overwrite": False,
1153        "inpath": True,
1154        "partition": False,
1155        "input_format": False,
1156        "serde": False,
1157    }
1158
1159
1160class Partition(Expression):
1161    arg_types = {"expressions": True}
1162
1163
1164class Fetch(Expression):
1165    arg_types = {"direction": False, "count": False}
1166
1167
1168class Group(Expression):
1169    arg_types = {
1170        "expressions": False,
1171        "grouping_sets": False,
1172        "cube": False,
1173        "rollup": False,
1174    }
1175
1176
1177class Lambda(Expression):
1178    arg_types = {"this": True, "expressions": True}
1179
1180
1181class Limit(Expression):
1182    arg_types = {"this": False, "expression": True}
1183
1184
1185class Literal(Condition):
1186    arg_types = {"this": True, "is_string": True}
1187
1188    def __eq__(self, other):
1189        return (
1190            isinstance(other, Literal)
1191            and self.this == other.this
1192            and self.args["is_string"] == other.args["is_string"]
1193        )
1194
1195    def __hash__(self):
1196        return hash((self.key, self.this, self.args["is_string"]))
1197
1198    @classmethod
1199    def number(cls, number) -> Literal:
1200        return cls(this=str(number), is_string=False)
1201
1202    @classmethod
1203    def string(cls, string) -> Literal:
1204        return cls(this=str(string), is_string=True)
1205
1206    @property
1207    def output_name(self):
1208        return self.name
1209
1210
1211class Join(Expression):
1212    arg_types = {
1213        "this": True,
1214        "on": False,
1215        "side": False,
1216        "kind": False,
1217        "using": False,
1218        "natural": False,
1219    }
1220
1221    @property
1222    def kind(self):
1223        return self.text("kind").upper()
1224
1225    @property
1226    def side(self):
1227        return self.text("side").upper()
1228
1229    @property
1230    def alias_or_name(self):
1231        return self.this.alias_or_name
1232
1233    def on(self, *expressions, append=True, dialect=None, copy=True, **opts):
1234        """
1235        Append to or set the ON expressions.
1236
1237        Example:
1238            >>> import sqlglot
1239            >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql()
1240            'JOIN x ON y = 1'
1241
1242        Args:
1243            *expressions (str | Expression): the SQL code strings to parse.
1244                If an `Expression` instance is passed, it will be used as-is.
1245                Multiple expressions are combined with an AND operator.
1246            append (bool): if `True`, AND the new expressions to any existing expression.
1247                Otherwise, this resets the expression.
1248            dialect (str): the dialect used to parse the input expressions.
1249            copy (bool): if `False`, modify this expression instance in-place.
1250            opts (kwargs): other options to use to parse the input expressions.
1251
1252        Returns:
1253            Join: the modified join expression.
1254        """
1255        join = _apply_conjunction_builder(
1256            *expressions,
1257            instance=self,
1258            arg="on",
1259            append=append,
1260            dialect=dialect,
1261            copy=copy,
1262            **opts,
1263        )
1264
1265        if join.kind == "CROSS":
1266            join.set("kind", None)
1267
1268        return join
1269
1270    def using(self, *expressions, append=True, dialect=None, copy=True, **opts):
1271        """
1272        Append to or set the USING expressions.
1273
1274        Example:
1275            >>> import sqlglot
1276            >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql()
1277            'JOIN x USING (foo, bla)'
1278
1279        Args:
1280            *expressions (str | Expression): the SQL code strings to parse.
1281                If an `Expression` instance is passed, it will be used as-is.
1282            append (bool): if `True`, concatenate the new expressions to the existing "using" list.
1283                Otherwise, this resets the expression.
1284            dialect (str): the dialect used to parse the input expressions.
1285            copy (bool): if `False`, modify this expression instance in-place.
1286            opts (kwargs): other options to use to parse the input expressions.
1287
1288        Returns:
1289            Join: the modified join expression.
1290        """
1291        join = _apply_list_builder(
1292            *expressions,
1293            instance=self,
1294            arg="using",
1295            append=append,
1296            dialect=dialect,
1297            copy=copy,
1298            **opts,
1299        )
1300
1301        if join.kind == "CROSS":
1302            join.set("kind", None)
1303
1304        return join
1305
1306
1307class Lateral(UDTF):
1308    arg_types = {"this": True, "view": False, "outer": False, "alias": False}
1309
1310
1311class MatchRecognize(Expression):
1312    arg_types = {
1313        "partition_by": False,
1314        "order": False,
1315        "measures": False,
1316        "rows": False,
1317        "after": False,
1318        "pattern": False,
1319        "define": False,
1320    }
1321
1322
1323# Clickhouse FROM FINAL modifier
1324# https://clickhouse.com/docs/en/sql-reference/statements/select/from/#final-modifier
1325class Final(Expression):
1326    pass
1327
1328
1329class Offset(Expression):
1330    arg_types = {"this": False, "expression": True}
1331
1332
1333class Order(Expression):
1334    arg_types = {"this": False, "expressions": True}
1335
1336
1337# hive specific sorts
1338# https://cwiki.apache.org/confluence/display/Hive/LanguageManual+SortBy
1339class Cluster(Order):
1340    pass
1341
1342
1343class Distribute(Order):
1344    pass
1345
1346
1347class Sort(Order):
1348    pass
1349
1350
1351class Ordered(Expression):
1352    arg_types = {"this": True, "desc": True, "nulls_first": True}
1353
1354
1355class Property(Expression):
1356    arg_types = {"this": True, "value": True}
1357
1358
1359class AfterJournalProperty(Property):
1360    arg_types = {"no": True, "dual": False, "local": False}
1361
1362
1363class AlgorithmProperty(Property):
1364    arg_types = {"this": True}
1365
1366
1367class AutoIncrementProperty(Property):
1368    arg_types = {"this": True}
1369
1370
1371class BlockCompressionProperty(Property):
1372    arg_types = {"autotemp": False, "always": False, "default": True, "manual": True, "never": True}
1373
1374
1375class CharacterSetProperty(Property):
1376    arg_types = {"this": True, "default": True}
1377
1378
1379class ChecksumProperty(Property):
1380    arg_types = {"on": False, "default": False}
1381
1382
1383class CollateProperty(Property):
1384    arg_types = {"this": True}
1385
1386
1387class DataBlocksizeProperty(Property):
1388    arg_types = {"size": False, "units": False, "min": False, "default": False}
1389
1390
1391class DefinerProperty(Property):
1392    arg_types = {"this": True}
1393
1394
1395class DistKeyProperty(Property):
1396    arg_types = {"this": True}
1397
1398
1399class DistStyleProperty(Property):
1400    arg_types = {"this": True}
1401
1402
1403class EngineProperty(Property):
1404    arg_types = {"this": True}
1405
1406
1407class ExecuteAsProperty(Property):
1408    arg_types = {"this": True}
1409
1410
1411class ExternalProperty(Property):
1412    arg_types = {"this": False}
1413
1414
1415class FallbackProperty(Property):
1416    arg_types = {"no": True, "protection": False}
1417
1418
1419class FileFormatProperty(Property):
1420    arg_types = {"this": True}
1421
1422
1423class FreespaceProperty(Property):
1424    arg_types = {"this": True, "percent": False}
1425
1426
1427class IsolatedLoadingProperty(Property):
1428    arg_types = {
1429        "no": True,
1430        "concurrent": True,
1431        "for_all": True,
1432        "for_insert": True,
1433        "for_none": True,
1434    }
1435
1436
1437class JournalProperty(Property):
1438    arg_types = {"no": True, "dual": False, "before": False}
1439
1440
1441class LanguageProperty(Property):
1442    arg_types = {"this": True}
1443
1444
1445class LikeProperty(Property):
1446    arg_types = {"this": True, "expressions": False}
1447
1448
1449class LocationProperty(Property):
1450    arg_types = {"this": True}
1451
1452
1453class LockingProperty(Property):
1454    arg_types = {
1455        "this": False,
1456        "kind": True,
1457        "for_or_in": True,
1458        "lock_type": True,
1459        "override": False,
1460    }
1461
1462
1463class LogProperty(Property):
1464    arg_types = {"no": True}
1465
1466
1467class MaterializedProperty(Property):
1468    arg_types = {"this": False}
1469
1470
1471class MergeBlockRatioProperty(Property):
1472    arg_types = {"this": False, "no": False, "default": False, "percent": False}
1473
1474
1475class NoPrimaryIndexProperty(Property):
1476    arg_types = {"this": False}
1477
1478
1479class OnCommitProperty(Property):
1480    arg_type = {"this": False}
1481
1482
1483class PartitionedByProperty(Property):
1484    arg_types = {"this": True}
1485
1486
1487class ReturnsProperty(Property):
1488    arg_types = {"this": True, "is_table": False, "table": False}
1489
1490
1491class RowFormatDelimitedProperty(Property):
1492    # https://cwiki.apache.org/confluence/display/hive/languagemanual+dml
1493    arg_types = {
1494        "fields": False,
1495        "escaped": False,
1496        "collection_items": False,
1497        "map_keys": False,
1498        "lines": False,
1499        "null": False,
1500        "serde": False,
1501    }
1502
1503
1504class RowFormatSerdeProperty(Property):
1505    arg_types = {"this": True}
1506
1507
1508class SchemaCommentProperty(Property):
1509    arg_types = {"this": True}
1510
1511
1512class SerdeProperties(Property):
1513    arg_types = {"expressions": True}
1514
1515
1516class SetProperty(Property):
1517    arg_types = {"multi": True}
1518
1519
1520class SortKeyProperty(Property):
1521    arg_types = {"this": True, "compound": False}
1522
1523
1524class SqlSecurityProperty(Property):
1525    arg_types = {"definer": True}
1526
1527
1528class TableFormatProperty(Property):
1529    arg_types = {"this": True}
1530
1531
1532class TemporaryProperty(Property):
1533    arg_types = {"global_": True}
1534
1535
1536class TransientProperty(Property):
1537    arg_types = {"this": False}
1538
1539
1540class VolatilityProperty(Property):
1541    arg_types = {"this": True}
1542
1543
1544class WithDataProperty(Property):
1545    arg_types = {"no": True, "statistics": False}
1546
1547
1548class WithJournalTableProperty(Property):
1549    arg_types = {"this": True}
1550
1551
1552class Properties(Expression):
1553    arg_types = {"expressions": True}
1554
1555    NAME_TO_PROPERTY = {
1556        "ALGORITHM": AlgorithmProperty,
1557        "AUTO_INCREMENT": AutoIncrementProperty,
1558        "CHARACTER SET": CharacterSetProperty,
1559        "COLLATE": CollateProperty,
1560        "COMMENT": SchemaCommentProperty,
1561        "DEFINER": DefinerProperty,
1562        "DISTKEY": DistKeyProperty,
1563        "DISTSTYLE": DistStyleProperty,
1564        "ENGINE": EngineProperty,
1565        "EXECUTE AS": ExecuteAsProperty,
1566        "FORMAT": FileFormatProperty,
1567        "LANGUAGE": LanguageProperty,
1568        "LOCATION": LocationProperty,
1569        "PARTITIONED_BY": PartitionedByProperty,
1570        "RETURNS": ReturnsProperty,
1571        "SORTKEY": SortKeyProperty,
1572        "TABLE_FORMAT": TableFormatProperty,
1573    }
1574
1575    PROPERTY_TO_NAME = {v: k for k, v in NAME_TO_PROPERTY.items()}
1576
1577    # CREATE property locations
1578    # Form: schema specified
1579    #   create [POST_CREATE]
1580    #     table a [POST_NAME]
1581    #     (b int) [POST_SCHEMA]
1582    #     with ([POST_WITH])
1583    #     index (b) [POST_INDEX]
1584    #
1585    # Form: alias selection
1586    #   create [POST_CREATE]
1587    #     table a [POST_NAME]
1588    #     as [POST_ALIAS] (select * from b) [POST_EXPRESSION]
1589    #     index (c) [POST_INDEX]
1590    class Location(AutoName):
1591        POST_CREATE = auto()
1592        POST_NAME = auto()
1593        POST_SCHEMA = auto()
1594        POST_WITH = auto()
1595        POST_ALIAS = auto()
1596        POST_EXPRESSION = auto()
1597        POST_INDEX = auto()
1598        UNSUPPORTED = auto()
1599
1600    @classmethod
1601    def from_dict(cls, properties_dict) -> Properties:
1602        expressions = []
1603        for key, value in properties_dict.items():
1604            property_cls = cls.NAME_TO_PROPERTY.get(key.upper())
1605            if property_cls:
1606                expressions.append(property_cls(this=convert(value)))
1607            else:
1608                expressions.append(Property(this=Literal.string(key), value=convert(value)))
1609
1610        return cls(expressions=expressions)
1611
1612
1613class Qualify(Expression):
1614    pass
1615
1616
1617# https://www.ibm.com/docs/en/ias?topic=procedures-return-statement-in-sql
1618class Return(Expression):
1619    pass
1620
1621
1622class Reference(Expression):
1623    arg_types = {"this": True, "expressions": False, "options": False}
1624
1625
1626class Tuple(Expression):
1627    arg_types = {"expressions": False}
1628
1629
1630class Subqueryable(Unionable):
1631    def subquery(self, alias=None, copy=True) -> Subquery:
1632        """
1633        Convert this expression to an aliased expression that can be used as a Subquery.
1634
1635        Example:
1636            >>> subquery = Select().select("x").from_("tbl").subquery()
1637            >>> Select().select("x").from_(subquery).sql()
1638            'SELECT x FROM (SELECT x FROM tbl)'
1639
1640        Args:
1641            alias (str | Identifier): an optional alias for the subquery
1642            copy (bool): if `False`, modify this expression instance in-place.
1643
1644        Returns:
1645            Alias: the subquery
1646        """
1647        instance = _maybe_copy(self, copy)
1648        return Subquery(
1649            this=instance,
1650            alias=TableAlias(this=to_identifier(alias)),
1651        )
1652
1653    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
1654        raise NotImplementedError
1655
1656    @property
1657    def ctes(self):
1658        with_ = self.args.get("with")
1659        if not with_:
1660            return []
1661        return with_.expressions
1662
1663    @property
1664    def selects(self):
1665        raise NotImplementedError("Subqueryable objects must implement `selects`")
1666
1667    @property
1668    def named_selects(self):
1669        raise NotImplementedError("Subqueryable objects must implement `named_selects`")
1670
1671    def with_(
1672        self,
1673        alias,
1674        as_,
1675        recursive=None,
1676        append=True,
1677        dialect=None,
1678        copy=True,
1679        **opts,
1680    ):
1681        """
1682        Append to or set the common table expressions.
1683
1684        Example:
1685            >>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql()
1686            'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2'
1687
1688        Args:
1689            alias (str | Expression): the SQL code string to parse as the table name.
1690                If an `Expression` instance is passed, this is used as-is.
1691            as_ (str | Expression): the SQL code string to parse as the table expression.
1692                If an `Expression` instance is passed, it will be used as-is.
1693            recursive (bool): set the RECURSIVE part of the expression. Defaults to `False`.
1694            append (bool): if `True`, add to any existing expressions.
1695                Otherwise, this resets the expressions.
1696            dialect (str): the dialect used to parse the input expression.
1697            copy (bool): if `False`, modify this expression instance in-place.
1698            opts (kwargs): other options to use to parse the input expressions.
1699
1700        Returns:
1701            Select: the modified expression.
1702        """
1703        alias_expression = maybe_parse(
1704            alias,
1705            dialect=dialect,
1706            into=TableAlias,
1707            **opts,
1708        )
1709        as_expression = maybe_parse(
1710            as_,
1711            dialect=dialect,
1712            **opts,
1713        )
1714        cte = CTE(
1715            this=as_expression,
1716            alias=alias_expression,
1717        )
1718        return _apply_child_list_builder(
1719            cte,
1720            instance=self,
1721            arg="with",
1722            append=append,
1723            copy=copy,
1724            into=With,
1725            properties={"recursive": recursive or False},
1726        )
1727
1728
1729QUERY_MODIFIERS = {
1730    "match": False,
1731    "laterals": False,
1732    "joins": False,
1733    "pivots": False,
1734    "where": False,
1735    "group": False,
1736    "having": False,
1737    "qualify": False,
1738    "windows": False,
1739    "distribute": False,
1740    "sort": False,
1741    "cluster": False,
1742    "order": False,
1743    "limit": False,
1744    "offset": False,
1745    "lock": False,
1746}
1747
1748
1749class Table(Expression):
1750    arg_types = {
1751        "this": True,
1752        "alias": False,
1753        "db": False,
1754        "catalog": False,
1755        "laterals": False,
1756        "joins": False,
1757        "pivots": False,
1758        "hints": False,
1759        "system_time": False,
1760    }
1761
1762    @property
1763    def db(self) -> str:
1764        return self.text("db")
1765
1766    @property
1767    def catalog(self) -> str:
1768        return self.text("catalog")
1769
1770
1771# See the TSQL "Querying data in a system-versioned temporal table" page
1772class SystemTime(Expression):
1773    arg_types = {
1774        "this": False,
1775        "expression": False,
1776        "kind": True,
1777    }
1778
1779
1780class Union(Subqueryable):
1781    arg_types = {
1782        "with": False,
1783        "this": True,
1784        "expression": True,
1785        "distinct": False,
1786        **QUERY_MODIFIERS,
1787    }
1788
1789    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
1790        """
1791        Set the LIMIT expression.
1792
1793        Example:
1794            >>> select("1").union(select("1")).limit(1).sql()
1795            'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1'
1796
1797        Args:
1798            expression (str | int | Expression): the SQL code string to parse.
1799                This can also be an integer.
1800                If a `Limit` instance is passed, this is used as-is.
1801                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
1802            dialect (str): the dialect used to parse the input expression.
1803            copy (bool): if `False`, modify this expression instance in-place.
1804            opts (kwargs): other options to use to parse the input expressions.
1805
1806        Returns:
1807            Select: The limited subqueryable.
1808        """
1809        return (
1810            select("*")
1811            .from_(self.subquery(alias="_l_0", copy=copy))
1812            .limit(expression, dialect=dialect, copy=False, **opts)
1813        )
1814
1815    def select(
1816        self,
1817        *expressions: str | Expression,
1818        append: bool = True,
1819        dialect: DialectType = None,
1820        copy: bool = True,
1821        **opts,
1822    ) -> Union:
1823        """Append to or set the SELECT of the union recursively.
1824
1825        Example:
1826            >>> from sqlglot import parse_one
1827            >>> parse_one("select a from x union select a from y union select a from z").select("b").sql()
1828            'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z'
1829
1830        Args:
1831            *expressions: the SQL code strings to parse.
1832                If an `Expression` instance is passed, it will be used as-is.
1833            append: if `True`, add to any existing expressions.
1834                Otherwise, this resets the expressions.
1835            dialect: the dialect used to parse the input expressions.
1836            copy: if `False`, modify this expression instance in-place.
1837            opts: other options to use to parse the input expressions.
1838
1839        Returns:
1840            Union: the modified expression.
1841        """
1842        this = self.copy() if copy else self
1843        this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts)
1844        this.expression.unnest().select(
1845            *expressions, append=append, dialect=dialect, copy=False, **opts
1846        )
1847        return this
1848
1849    @property
1850    def named_selects(self):
1851        return self.this.unnest().named_selects
1852
1853    @property
1854    def is_star(self) -> bool:
1855        return self.this.is_star or self.expression.is_star
1856
1857    @property
1858    def selects(self):
1859        return self.this.unnest().selects
1860
1861    @property
1862    def left(self):
1863        return self.this
1864
1865    @property
1866    def right(self):
1867        return self.expression
1868
1869
1870class Except(Union):
1871    pass
1872
1873
1874class Intersect(Union):
1875    pass
1876
1877
1878class Unnest(UDTF):
1879    arg_types = {
1880        "expressions": True,
1881        "ordinality": False,
1882        "alias": False,
1883        "offset": False,
1884    }
1885
1886
1887class Update(Expression):
1888    arg_types = {
1889        "with": False,
1890        "this": False,
1891        "expressions": True,
1892        "from": False,
1893        "where": False,
1894    }
1895
1896
1897class Values(UDTF):
1898    arg_types = {
1899        "expressions": True,
1900        "ordinality": False,
1901        "alias": False,
1902    }
1903
1904
1905class Var(Expression):
1906    pass
1907
1908
1909class Schema(Expression):
1910    arg_types = {"this": False, "expressions": False}
1911
1912
1913# Used to represent the FOR UPDATE and FOR SHARE locking read types.
1914# https://dev.mysql.com/doc/refman/8.0/en/innodb-locking-reads.html
1915class Lock(Expression):
1916    arg_types = {"update": True}
1917
1918
1919class Select(Subqueryable):
1920    arg_types = {
1921        "with": False,
1922        "expressions": False,
1923        "hint": False,
1924        "distinct": False,
1925        "into": False,
1926        "from": False,
1927        **QUERY_MODIFIERS,
1928    }
1929
1930    def from_(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1931        """
1932        Set the FROM expression.
1933
1934        Example:
1935            >>> Select().from_("tbl").select("x").sql()
1936            'SELECT x FROM tbl'
1937
1938        Args:
1939            *expressions (str | Expression): the SQL code strings to parse.
1940                If a `From` instance is passed, this is used as-is.
1941                If another `Expression` instance is passed, it will be wrapped in a `From`.
1942            append (bool): if `True`, add to any existing expressions.
1943                Otherwise, this flattens all the `From` expression into a single expression.
1944            dialect (str): the dialect used to parse the input expression.
1945            copy (bool): if `False`, modify this expression instance in-place.
1946            opts (kwargs): other options to use to parse the input expressions.
1947
1948        Returns:
1949            Select: the modified expression.
1950        """
1951        return _apply_child_list_builder(
1952            *expressions,
1953            instance=self,
1954            arg="from",
1955            append=append,
1956            copy=copy,
1957            prefix="FROM",
1958            into=From,
1959            dialect=dialect,
1960            **opts,
1961        )
1962
1963    def group_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1964        """
1965        Set the GROUP BY expression.
1966
1967        Example:
1968            >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql()
1969            'SELECT x, COUNT(1) FROM tbl GROUP BY x'
1970
1971        Args:
1972            *expressions (str | Expression): the SQL code strings to parse.
1973                If a `Group` instance is passed, this is used as-is.
1974                If another `Expression` instance is passed, it will be wrapped in a `Group`.
1975                If nothing is passed in then a group by is not applied to the expression
1976            append (bool): if `True`, add to any existing expressions.
1977                Otherwise, this flattens all the `Group` expression into a single expression.
1978            dialect (str): the dialect used to parse the input expression.
1979            copy (bool): if `False`, modify this expression instance in-place.
1980            opts (kwargs): other options to use to parse the input expressions.
1981
1982        Returns:
1983            Select: the modified expression.
1984        """
1985        if not expressions:
1986            return self if not copy else self.copy()
1987        return _apply_child_list_builder(
1988            *expressions,
1989            instance=self,
1990            arg="group",
1991            append=append,
1992            copy=copy,
1993            prefix="GROUP BY",
1994            into=Group,
1995            dialect=dialect,
1996            **opts,
1997        )
1998
1999    def order_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2000        """
2001        Set the ORDER BY expression.
2002
2003        Example:
2004            >>> Select().from_("tbl").select("x").order_by("x DESC").sql()
2005            'SELECT x FROM tbl ORDER BY x DESC'
2006
2007        Args:
2008            *expressions (str | Expression): the SQL code strings to parse.
2009                If a `Group` instance is passed, this is used as-is.
2010                If another `Expression` instance is passed, it will be wrapped in a `Order`.
2011            append (bool): if `True`, add to any existing expressions.
2012                Otherwise, this flattens all the `Order` expression into a single expression.
2013            dialect (str): the dialect used to parse the input expression.
2014            copy (bool): if `False`, modify this expression instance in-place.
2015            opts (kwargs): other options to use to parse the input expressions.
2016
2017        Returns:
2018            Select: the modified expression.
2019        """
2020        return _apply_child_list_builder(
2021            *expressions,
2022            instance=self,
2023            arg="order",
2024            append=append,
2025            copy=copy,
2026            prefix="ORDER BY",
2027            into=Order,
2028            dialect=dialect,
2029            **opts,
2030        )
2031
2032    def sort_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2033        """
2034        Set the SORT BY expression.
2035
2036        Example:
2037            >>> Select().from_("tbl").select("x").sort_by("x DESC").sql()
2038            'SELECT x FROM tbl SORT BY x DESC'
2039
2040        Args:
2041            *expressions (str | Expression): the SQL code strings to parse.
2042                If a `Group` instance is passed, this is used as-is.
2043                If another `Expression` instance is passed, it will be wrapped in a `SORT`.
2044            append (bool): if `True`, add to any existing expressions.
2045                Otherwise, this flattens all the `Order` expression into a single expression.
2046            dialect (str): the dialect used to parse the input expression.
2047            copy (bool): if `False`, modify this expression instance in-place.
2048            opts (kwargs): other options to use to parse the input expressions.
2049
2050        Returns:
2051            Select: the modified expression.
2052        """
2053        return _apply_child_list_builder(
2054            *expressions,
2055            instance=self,
2056            arg="sort",
2057            append=append,
2058            copy=copy,
2059            prefix="SORT BY",
2060            into=Sort,
2061            dialect=dialect,
2062            **opts,
2063        )
2064
2065    def cluster_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2066        """
2067        Set the CLUSTER BY expression.
2068
2069        Example:
2070            >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql()
2071            'SELECT x FROM tbl CLUSTER BY x DESC'
2072
2073        Args:
2074            *expressions (str | Expression): the SQL code strings to parse.
2075                If a `Group` instance is passed, this is used as-is.
2076                If another `Expression` instance is passed, it will be wrapped in a `Cluster`.
2077            append (bool): if `True`, add to any existing expressions.
2078                Otherwise, this flattens all the `Order` expression into a single expression.
2079            dialect (str): the dialect used to parse the input expression.
2080            copy (bool): if `False`, modify this expression instance in-place.
2081            opts (kwargs): other options to use to parse the input expressions.
2082
2083        Returns:
2084            Select: the modified expression.
2085        """
2086        return _apply_child_list_builder(
2087            *expressions,
2088            instance=self,
2089            arg="cluster",
2090            append=append,
2091            copy=copy,
2092            prefix="CLUSTER BY",
2093            into=Cluster,
2094            dialect=dialect,
2095            **opts,
2096        )
2097
2098    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
2099        """
2100        Set the LIMIT expression.
2101
2102        Example:
2103            >>> Select().from_("tbl").select("x").limit(10).sql()
2104            'SELECT x FROM tbl LIMIT 10'
2105
2106        Args:
2107            expression (str | int | Expression): the SQL code string to parse.
2108                This can also be an integer.
2109                If a `Limit` instance is passed, this is used as-is.
2110                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
2111            dialect (str): the dialect used to parse the input expression.
2112            copy (bool): if `False`, modify this expression instance in-place.
2113            opts (kwargs): other options to use to parse the input expressions.
2114
2115        Returns:
2116            Select: the modified expression.
2117        """
2118        return _apply_builder(
2119            expression=expression,
2120            instance=self,
2121            arg="limit",
2122            into=Limit,
2123            prefix="LIMIT",
2124            dialect=dialect,
2125            copy=copy,
2126            **opts,
2127        )
2128
2129    def offset(self, expression, dialect=None, copy=True, **opts) -> Select:
2130        """
2131        Set the OFFSET expression.
2132
2133        Example:
2134            >>> Select().from_("tbl").select("x").offset(10).sql()
2135            'SELECT x FROM tbl OFFSET 10'
2136
2137        Args:
2138            expression (str | int | Expression): the SQL code string to parse.
2139                This can also be an integer.
2140                If a `Offset` instance is passed, this is used as-is.
2141                If another `Expression` instance is passed, it will be wrapped in a `Offset`.
2142            dialect (str): the dialect used to parse the input expression.
2143            copy (bool): if `False`, modify this expression instance in-place.
2144            opts (kwargs): other options to use to parse the input expressions.
2145
2146        Returns:
2147            Select: the modified expression.
2148        """
2149        return _apply_builder(
2150            expression=expression,
2151            instance=self,
2152            arg="offset",
2153            into=Offset,
2154            prefix="OFFSET",
2155            dialect=dialect,
2156            copy=copy,
2157            **opts,
2158        )
2159
2160    def select(
2161        self,
2162        *expressions: str | Expression,
2163        append: bool = True,
2164        dialect: DialectType = None,
2165        copy: bool = True,
2166        **opts,
2167    ) -> Select:
2168        """
2169        Append to or set the SELECT expressions.
2170
2171        Example:
2172            >>> Select().select("x", "y").sql()
2173            'SELECT x, y'
2174
2175        Args:
2176            *expressions: the SQL code strings to parse.
2177                If an `Expression` instance is passed, it will be used as-is.
2178            append: if `True`, add to any existing expressions.
2179                Otherwise, this resets the expressions.
2180            dialect: the dialect used to parse the input expressions.
2181            copy: if `False`, modify this expression instance in-place.
2182            opts: other options to use to parse the input expressions.
2183
2184        Returns:
2185            Select: the modified expression.
2186        """
2187        return _apply_list_builder(
2188            *expressions,
2189            instance=self,
2190            arg="expressions",
2191            append=append,
2192            dialect=dialect,
2193            copy=copy,
2194            **opts,
2195        )
2196
2197    def lateral(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2198        """
2199        Append to or set the LATERAL expressions.
2200
2201        Example:
2202            >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql()
2203            'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
2204
2205        Args:
2206            *expressions (str | Expression): the SQL code strings to parse.
2207                If an `Expression` instance is passed, it will be used as-is.
2208            append (bool): if `True`, add to any existing expressions.
2209                Otherwise, this resets the expressions.
2210            dialect (str): the dialect used to parse the input expressions.
2211            copy (bool): if `False`, modify this expression instance in-place.
2212            opts (kwargs): other options to use to parse the input expressions.
2213
2214        Returns:
2215            Select: the modified expression.
2216        """
2217        return _apply_list_builder(
2218            *expressions,
2219            instance=self,
2220            arg="laterals",
2221            append=append,
2222            into=Lateral,
2223            prefix="LATERAL VIEW",
2224            dialect=dialect,
2225            copy=copy,
2226            **opts,
2227        )
2228
2229    def join(
2230        self,
2231        expression,
2232        on=None,
2233        using=None,
2234        append=True,
2235        join_type=None,
2236        join_alias=None,
2237        dialect=None,
2238        copy=True,
2239        **opts,
2240    ) -> Select:
2241        """
2242        Append to or set the JOIN expressions.
2243
2244        Example:
2245            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql()
2246            'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'
2247
2248            >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql()
2249            'SELECT 1 FROM a JOIN b USING (x, y, z)'
2250
2251            Use `join_type` to change the type of join:
2252
2253            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql()
2254            'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
2255
2256        Args:
2257            expression (str | Expression): the SQL code string to parse.
2258                If an `Expression` instance is passed, it will be used as-is.
2259            on (str | Expression): optionally specify the join "on" criteria as a SQL string.
2260                If an `Expression` instance is passed, it will be used as-is.
2261            using (str | Expression): optionally specify the join "using" criteria as a SQL string.
2262                If an `Expression` instance is passed, it will be used as-is.
2263            append (bool): if `True`, add to any existing expressions.
2264                Otherwise, this resets the expressions.
2265            join_type (str): If set, alter the parsed join type
2266            dialect (str): the dialect used to parse the input expressions.
2267            copy (bool): if `False`, modify this expression instance in-place.
2268            opts (kwargs): other options to use to parse the input expressions.
2269
2270        Returns:
2271            Select: the modified expression.
2272        """
2273        parse_args = {"dialect": dialect, **opts}
2274
2275        try:
2276            expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args)
2277        except ParseError:
2278            expression = maybe_parse(expression, into=(Join, Expression), **parse_args)
2279
2280        join = expression if isinstance(expression, Join) else Join(this=expression)
2281
2282        if isinstance(join.this, Select):
2283            join.this.replace(join.this.subquery())
2284
2285        if join_type:
2286            natural: t.Optional[Token]
2287            side: t.Optional[Token]
2288            kind: t.Optional[Token]
2289
2290            natural, side, kind = maybe_parse(join_type, into="JOIN_TYPE", **parse_args)  # type: ignore
2291
2292            if natural:
2293                join.set("natural", True)
2294            if side:
2295                join.set("side", side.text)
2296            if kind:
2297                join.set("kind", kind.text)
2298
2299        if on:
2300            on = and_(*ensure_collection(on), dialect=dialect, **opts)
2301            join.set("on", on)
2302
2303        if using:
2304            join = _apply_list_builder(
2305                *ensure_collection(using),
2306                instance=join,
2307                arg="using",
2308                append=append,
2309                copy=copy,
2310                **opts,
2311            )
2312
2313        if join_alias:
2314            join.set("this", alias_(join.this, join_alias, table=True))
2315        return _apply_list_builder(
2316            join,
2317            instance=self,
2318            arg="joins",
2319            append=append,
2320            copy=copy,
2321            **opts,
2322        )
2323
2324    def where(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2325        """
2326        Append to or set the WHERE expressions.
2327
2328        Example:
2329            >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql()
2330            "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
2331
2332        Args:
2333            *expressions (str | Expression): the SQL code strings to parse.
2334                If an `Expression` instance is passed, it will be used as-is.
2335                Multiple expressions are combined with an AND operator.
2336            append (bool): if `True`, AND the new expressions to any existing expression.
2337                Otherwise, this resets the expression.
2338            dialect (str): the dialect used to parse the input expressions.
2339            copy (bool): if `False`, modify this expression instance in-place.
2340            opts (kwargs): other options to use to parse the input expressions.
2341
2342        Returns:
2343            Select: the modified expression.
2344        """
2345        return _apply_conjunction_builder(
2346            *expressions,
2347            instance=self,
2348            arg="where",
2349            append=append,
2350            into=Where,
2351            dialect=dialect,
2352            copy=copy,
2353            **opts,
2354        )
2355
2356    def having(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2357        """
2358        Append to or set the HAVING expressions.
2359
2360        Example:
2361            >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql()
2362            'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
2363
2364        Args:
2365            *expressions (str | Expression): the SQL code strings to parse.
2366                If an `Expression` instance is passed, it will be used as-is.
2367                Multiple expressions are combined with an AND operator.
2368            append (bool): if `True`, AND the new expressions to any existing expression.
2369                Otherwise, this resets the expression.
2370            dialect (str): the dialect used to parse the input expressions.
2371            copy (bool): if `False`, modify this expression instance in-place.
2372            opts (kwargs): other options to use to parse the input expressions.
2373
2374        Returns:
2375            Select: the modified expression.
2376        """
2377        return _apply_conjunction_builder(
2378            *expressions,
2379            instance=self,
2380            arg="having",
2381            append=append,
2382            into=Having,
2383            dialect=dialect,
2384            copy=copy,
2385            **opts,
2386        )
2387
2388    def window(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2389        return _apply_list_builder(
2390            *expressions,
2391            instance=self,
2392            arg="windows",
2393            append=append,
2394            into=Window,
2395            dialect=dialect,
2396            copy=copy,
2397            **opts,
2398        )
2399
2400    def distinct(self, distinct=True, copy=True) -> Select:
2401        """
2402        Set the OFFSET expression.
2403
2404        Example:
2405            >>> Select().from_("tbl").select("x").distinct().sql()
2406            'SELECT DISTINCT x FROM tbl'
2407
2408        Args:
2409            distinct (bool): whether the Select should be distinct
2410            copy (bool): if `False`, modify this expression instance in-place.
2411
2412        Returns:
2413            Select: the modified expression.
2414        """
2415        instance = _maybe_copy(self, copy)
2416        instance.set("distinct", Distinct() if distinct else None)
2417        return instance
2418
2419    def ctas(self, table, properties=None, dialect=None, copy=True, **opts) -> Create:
2420        """
2421        Convert this expression to a CREATE TABLE AS statement.
2422
2423        Example:
2424            >>> Select().select("*").from_("tbl").ctas("x").sql()
2425            'CREATE TABLE x AS SELECT * FROM tbl'
2426
2427        Args:
2428            table (str | Expression): the SQL code string to parse as the table name.
2429                If another `Expression` instance is passed, it will be used as-is.
2430            properties (dict): an optional mapping of table properties
2431            dialect (str): the dialect used to parse the input table.
2432            copy (bool): if `False`, modify this expression instance in-place.
2433            opts (kwargs): other options to use to parse the input table.
2434
2435        Returns:
2436            Create: the CREATE TABLE AS expression
2437        """
2438        instance = _maybe_copy(self, copy)
2439        table_expression = maybe_parse(
2440            table,
2441            into=Table,
2442            dialect=dialect,
2443            **opts,
2444        )
2445        properties_expression = None
2446        if properties:
2447            properties_expression = Properties.from_dict(properties)
2448
2449        return Create(
2450            this=table_expression,
2451            kind="table",
2452            expression=instance,
2453            properties=properties_expression,
2454        )
2455
2456    def lock(self, update: bool = True, copy: bool = True) -> Select:
2457        """
2458        Set the locking read mode for this expression.
2459
2460        Examples:
2461            >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql")
2462            "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE"
2463
2464            >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql")
2465            "SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
2466
2467        Args:
2468            update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`.
2469            copy: if `False`, modify this expression instance in-place.
2470
2471        Returns:
2472            The modified expression.
2473        """
2474
2475        inst = _maybe_copy(self, copy)
2476        inst.set("lock", Lock(update=update))
2477
2478        return inst
2479
2480    @property
2481    def named_selects(self) -> t.List[str]:
2482        return [e.output_name for e in self.expressions if e.alias_or_name]
2483
2484    @property
2485    def is_star(self) -> bool:
2486        return any(expression.is_star for expression in self.expressions)
2487
2488    @property
2489    def selects(self) -> t.List[Expression]:
2490        return self.expressions
2491
2492
2493class Subquery(DerivedTable, Unionable):
2494    arg_types = {
2495        "this": True,
2496        "alias": False,
2497        "with": False,
2498        **QUERY_MODIFIERS,
2499    }
2500
2501    def unnest(self):
2502        """
2503        Returns the first non subquery.
2504        """
2505        expression = self
2506        while isinstance(expression, Subquery):
2507            expression = expression.this
2508        return expression
2509
2510    @property
2511    def is_star(self) -> bool:
2512        return self.this.is_star
2513
2514    @property
2515    def output_name(self):
2516        return self.alias
2517
2518
2519class TableSample(Expression):
2520    arg_types = {
2521        "this": False,
2522        "method": False,
2523        "bucket_numerator": False,
2524        "bucket_denominator": False,
2525        "bucket_field": False,
2526        "percent": False,
2527        "rows": False,
2528        "size": False,
2529        "seed": False,
2530    }
2531
2532
2533class Tag(Expression):
2534    """Tags are used for generating arbitrary sql like SELECT <span>x</span>."""
2535
2536    arg_types = {
2537        "this": False,
2538        "prefix": False,
2539        "postfix": False,
2540    }
2541
2542
2543class Pivot(Expression):
2544    arg_types = {
2545        "this": False,
2546        "alias": False,
2547        "expressions": True,
2548        "field": True,
2549        "unpivot": True,
2550    }
2551
2552
2553class Window(Expression):
2554    arg_types = {
2555        "this": True,
2556        "partition_by": False,
2557        "order": False,
2558        "spec": False,
2559        "alias": False,
2560    }
2561
2562
2563class WindowSpec(Expression):
2564    arg_types = {
2565        "kind": False,
2566        "start": False,
2567        "start_side": False,
2568        "end": False,
2569        "end_side": False,
2570    }
2571
2572
2573class Where(Expression):
2574    pass
2575
2576
2577class Star(Expression):
2578    arg_types = {"except": False, "replace": False}
2579
2580    @property
2581    def name(self) -> str:
2582        return "*"
2583
2584    @property
2585    def output_name(self):
2586        return self.name
2587
2588
2589class Parameter(Expression):
2590    arg_types = {"this": True, "wrapped": False}
2591
2592
2593class SessionParameter(Expression):
2594    arg_types = {"this": True, "kind": False}
2595
2596
2597class Placeholder(Expression):
2598    arg_types = {"this": False}
2599
2600
2601class Null(Condition):
2602    arg_types: t.Dict[str, t.Any] = {}
2603
2604    @property
2605    def name(self) -> str:
2606        return "NULL"
2607
2608
2609class Boolean(Condition):
2610    pass
2611
2612
2613class DataType(Expression):
2614    arg_types = {
2615        "this": True,
2616        "expressions": False,
2617        "nested": False,
2618        "values": False,
2619        "prefix": False,
2620    }
2621
2622    class Type(AutoName):
2623        CHAR = auto()
2624        NCHAR = auto()
2625        VARCHAR = auto()
2626        NVARCHAR = auto()
2627        TEXT = auto()
2628        MEDIUMTEXT = auto()
2629        LONGTEXT = auto()
2630        MEDIUMBLOB = auto()
2631        LONGBLOB = auto()
2632        BINARY = auto()
2633        VARBINARY = auto()
2634        INT = auto()
2635        TINYINT = auto()
2636        SMALLINT = auto()
2637        BIGINT = auto()
2638        FLOAT = auto()
2639        DOUBLE = auto()
2640        DECIMAL = auto()
2641        BOOLEAN = auto()
2642        JSON = auto()
2643        JSONB = auto()
2644        INTERVAL = auto()
2645        TIME = auto()
2646        TIMESTAMP = auto()
2647        TIMESTAMPTZ = auto()
2648        TIMESTAMPLTZ = auto()
2649        DATE = auto()
2650        DATETIME = auto()
2651        ARRAY = auto()
2652        MAP = auto()
2653        UUID = auto()
2654        GEOGRAPHY = auto()
2655        GEOMETRY = auto()
2656        STRUCT = auto()
2657        NULLABLE = auto()
2658        HLLSKETCH = auto()
2659        HSTORE = auto()
2660        SUPER = auto()
2661        SERIAL = auto()
2662        SMALLSERIAL = auto()
2663        BIGSERIAL = auto()
2664        XML = auto()
2665        UNIQUEIDENTIFIER = auto()
2666        MONEY = auto()
2667        SMALLMONEY = auto()
2668        ROWVERSION = auto()
2669        IMAGE = auto()
2670        VARIANT = auto()
2671        OBJECT = auto()
2672        INET = auto()
2673        NULL = auto()
2674        UNKNOWN = auto()  # Sentinel value, useful for type annotation
2675
2676    TEXT_TYPES = {
2677        Type.CHAR,
2678        Type.NCHAR,
2679        Type.VARCHAR,
2680        Type.NVARCHAR,
2681        Type.TEXT,
2682    }
2683
2684    INTEGER_TYPES = {
2685        Type.INT,
2686        Type.TINYINT,
2687        Type.SMALLINT,
2688        Type.BIGINT,
2689    }
2690
2691    FLOAT_TYPES = {
2692        Type.FLOAT,
2693        Type.DOUBLE,
2694    }
2695
2696    NUMERIC_TYPES = {*INTEGER_TYPES, *FLOAT_TYPES}
2697
2698    TEMPORAL_TYPES = {
2699        Type.TIMESTAMP,
2700        Type.TIMESTAMPTZ,
2701        Type.TIMESTAMPLTZ,
2702        Type.DATE,
2703        Type.DATETIME,
2704    }
2705
2706    @classmethod
2707    def build(
2708        cls, dtype: str | DataType | DataType.Type, dialect: DialectType = None, **kwargs
2709    ) -> DataType:
2710        from sqlglot import parse_one
2711
2712        if isinstance(dtype, str):
2713            if dtype.upper() in cls.Type.__members__:
2714                data_type_exp: t.Optional[Expression] = DataType(this=DataType.Type[dtype.upper()])
2715            else:
2716                data_type_exp = parse_one(dtype, read=dialect, into=DataType)
2717            if data_type_exp is None:
2718                raise ValueError(f"Unparsable data type value: {dtype}")
2719        elif isinstance(dtype, DataType.Type):
2720            data_type_exp = DataType(this=dtype)
2721        elif isinstance(dtype, DataType):
2722            return dtype
2723        else:
2724            raise ValueError(f"Invalid data type: {type(dtype)}. Expected str or DataType.Type")
2725        return DataType(**{**data_type_exp.args, **kwargs})
2726
2727    def is_type(self, dtype: DataType.Type) -> bool:
2728        return self.this == dtype
2729
2730
2731# https://www.postgresql.org/docs/15/datatype-pseudo.html
2732class PseudoType(Expression):
2733    pass
2734
2735
2736class StructKwarg(Expression):
2737    arg_types = {"this": True, "expression": True}
2738
2739
2740# WHERE x <OP> EXISTS|ALL|ANY|SOME(SELECT ...)
2741class SubqueryPredicate(Predicate):
2742    pass
2743
2744
2745class All(SubqueryPredicate):
2746    pass
2747
2748
2749class Any(SubqueryPredicate):
2750    pass
2751
2752
2753class Exists(SubqueryPredicate):
2754    pass
2755
2756
2757# Commands to interact with the databases or engines. For most of the command
2758# expressions we parse whatever comes after the command's name as a string.
2759class Command(Expression):
2760    arg_types = {"this": True, "expression": False}
2761
2762
2763class Transaction(Expression):
2764    arg_types = {"this": False, "modes": False}
2765
2766
2767class Commit(Expression):
2768    arg_types = {"chain": False}
2769
2770
2771class Rollback(Expression):
2772    arg_types = {"savepoint": False}
2773
2774
2775class AlterTable(Expression):
2776    arg_types = {"this": True, "actions": True, "exists": False}
2777
2778
2779class AddConstraint(Expression):
2780    arg_types = {"this": False, "expression": False, "enforced": False}
2781
2782
2783class DropPartition(Expression):
2784    arg_types = {"expressions": True, "exists": False}
2785
2786
2787# Binary expressions like (ADD a b)
2788class Binary(Expression):
2789    arg_types = {"this": True, "expression": True}
2790
2791    @property
2792    def left(self):
2793        return self.this
2794
2795    @property
2796    def right(self):
2797        return self.expression
2798
2799
2800class Add(Binary):
2801    pass
2802
2803
2804class Connector(Binary, Condition):
2805    pass
2806
2807
2808class And(Connector):
2809    pass
2810
2811
2812class Or(Connector):
2813    pass
2814
2815
2816class BitwiseAnd(Binary):
2817    pass
2818
2819
2820class BitwiseLeftShift(Binary):
2821    pass
2822
2823
2824class BitwiseOr(Binary):
2825    pass
2826
2827
2828class BitwiseRightShift(Binary):
2829    pass
2830
2831
2832class BitwiseXor(Binary):
2833    pass
2834
2835
2836class Div(Binary):
2837    pass
2838
2839
2840class Overlaps(Binary):
2841    pass
2842
2843
2844class Dot(Binary):
2845    @property
2846    def name(self) -> str:
2847        return self.expression.name
2848
2849
2850class DPipe(Binary):
2851    pass
2852
2853
2854class EQ(Binary, Predicate):
2855    pass
2856
2857
2858class NullSafeEQ(Binary, Predicate):
2859    pass
2860
2861
2862class NullSafeNEQ(Binary, Predicate):
2863    pass
2864
2865
2866class Distance(Binary):
2867    pass
2868
2869
2870class Escape(Binary):
2871    pass
2872
2873
2874class Glob(Binary, Predicate):
2875    pass
2876
2877
2878class GT(Binary, Predicate):
2879    pass
2880
2881
2882class GTE(Binary, Predicate):
2883    pass
2884
2885
2886class ILike(Binary, Predicate):
2887    pass
2888
2889
2890class ILikeAny(Binary, Predicate):
2891    pass
2892
2893
2894class IntDiv(Binary):
2895    pass
2896
2897
2898class Is(Binary, Predicate):
2899    pass
2900
2901
2902class Kwarg(Binary):
2903    """Kwarg in special functions like func(kwarg => y)."""
2904
2905
2906class Like(Binary, Predicate):
2907    pass
2908
2909
2910class LikeAny(Binary, Predicate):
2911    pass
2912
2913
2914class LT(Binary, Predicate):
2915    pass
2916
2917
2918class LTE(Binary, Predicate):
2919    pass
2920
2921
2922class Mod(Binary):
2923    pass
2924
2925
2926class Mul(Binary):
2927    pass
2928
2929
2930class NEQ(Binary, Predicate):
2931    pass
2932
2933
2934class SimilarTo(Binary, Predicate):
2935    pass
2936
2937
2938class Slice(Binary):
2939    arg_types = {"this": False, "expression": False}
2940
2941
2942class Sub(Binary):
2943    pass
2944
2945
2946# Unary Expressions
2947# (NOT a)
2948class Unary(Expression):
2949    pass
2950
2951
2952class BitwiseNot(Unary):
2953    pass
2954
2955
2956class Not(Unary, Condition):
2957    pass
2958
2959
2960class Paren(Unary, Condition):
2961    arg_types = {"this": True, "with": False}
2962
2963
2964class Neg(Unary):
2965    pass
2966
2967
2968# Special Functions
2969class Alias(Expression):
2970    arg_types = {"this": True, "alias": False}
2971
2972    @property
2973    def output_name(self):
2974        return self.alias
2975
2976
2977class Aliases(Expression):
2978    arg_types = {"this": True, "expressions": True}
2979
2980    @property
2981    def aliases(self):
2982        return self.expressions
2983
2984
2985class AtTimeZone(Expression):
2986    arg_types = {"this": True, "zone": True}
2987
2988
2989class Between(Predicate):
2990    arg_types = {"this": True, "low": True, "high": True}
2991
2992
2993class Bracket(Condition):
2994    arg_types = {"this": True, "expressions": True}
2995
2996
2997class Distinct(Expression):
2998    arg_types = {"expressions": False, "on": False}
2999
3000
3001class In(Predicate):
3002    arg_types = {
3003        "this": True,
3004        "expressions": False,
3005        "query": False,
3006        "unnest": False,
3007        "field": False,
3008        "is_global": False,
3009    }
3010
3011
3012class TimeUnit(Expression):
3013    """Automatically converts unit arg into a var."""
3014
3015    arg_types = {"unit": False}
3016
3017    def __init__(self, **args):
3018        unit = args.get("unit")
3019        if isinstance(unit, Column):
3020            args["unit"] = Var(this=unit.name)
3021        elif isinstance(unit, Week):
3022            unit.set("this", Var(this=unit.this.name))
3023        super().__init__(**args)
3024
3025
3026class Interval(TimeUnit):
3027    arg_types = {"this": False, "unit": False}
3028
3029
3030class IgnoreNulls(Expression):
3031    pass
3032
3033
3034class RespectNulls(Expression):
3035    pass
3036
3037
3038# Functions
3039class Func(Condition):
3040    """
3041    The base class for all function expressions.
3042
3043    Attributes:
3044        is_var_len_args (bool): if set to True the last argument defined in arg_types will be
3045            treated as a variable length argument and the argument's value will be stored as a list.
3046        _sql_names (list): determines the SQL name (1st item in the list) and aliases (subsequent items)
3047            for this function expression. These values are used to map this node to a name during parsing
3048            as well as to provide the function's name during SQL string generation. By default the SQL
3049            name is set to the expression's class name transformed to snake case.
3050    """
3051
3052    is_var_len_args = False
3053
3054    @classmethod
3055    def from_arg_list(cls, args):
3056        if cls.is_var_len_args:
3057            all_arg_keys = list(cls.arg_types)
3058            # If this function supports variable length argument treat the last argument as such.
3059            non_var_len_arg_keys = all_arg_keys[:-1] if cls.is_var_len_args else all_arg_keys
3060            num_non_var = len(non_var_len_arg_keys)
3061
3062            args_dict = {arg_key: arg for arg, arg_key in zip(args, non_var_len_arg_keys)}
3063            args_dict[all_arg_keys[-1]] = args[num_non_var:]
3064        else:
3065            args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)}
3066
3067        return cls(**args_dict)
3068
3069    @classmethod
3070    def sql_names(cls):
3071        if cls is Func:
3072            raise NotImplementedError(
3073                "SQL name is only supported by concrete function implementations"
3074            )
3075        if "_sql_names" not in cls.__dict__:
3076            cls._sql_names = [camel_to_snake_case(cls.__name__)]
3077        return cls._sql_names
3078
3079    @classmethod
3080    def sql_name(cls):
3081        return cls.sql_names()[0]
3082
3083    @classmethod
3084    def default_parser_mappings(cls):
3085        return {name: cls.from_arg_list for name in cls.sql_names()}
3086
3087
3088class AggFunc(Func):
3089    pass
3090
3091
3092class Abs(Func):
3093    pass
3094
3095
3096class Anonymous(Func):
3097    arg_types = {"this": True, "expressions": False}
3098    is_var_len_args = True
3099
3100
3101class ApproxDistinct(AggFunc):
3102    arg_types = {"this": True, "accuracy": False}
3103
3104
3105class Array(Func):
3106    arg_types = {"expressions": False}
3107    is_var_len_args = True
3108
3109
3110class GenerateSeries(Func):
3111    arg_types = {"start": True, "end": True, "step": False}
3112
3113
3114class ArrayAgg(AggFunc):
3115    pass
3116
3117
3118class ArrayAll(Func):
3119    arg_types = {"this": True, "expression": True}
3120
3121
3122class ArrayAny(Func):
3123    arg_types = {"this": True, "expression": True}
3124
3125
3126class ArrayConcat(Func):
3127    arg_types = {"this": True, "expressions": False}
3128    is_var_len_args = True
3129
3130
3131class ArrayContains(Func):
3132    arg_types = {"this": True, "expression": True}
3133
3134
3135class ArrayFilter(Func):
3136    arg_types = {"this": True, "expression": True}
3137    _sql_names = ["FILTER", "ARRAY_FILTER"]
3138
3139
3140class ArrayJoin(Func):
3141    arg_types = {"this": True, "expression": True, "null": False}
3142
3143
3144class ArraySize(Func):
3145    arg_types = {"this": True, "expression": False}
3146
3147
3148class ArraySort(Func):
3149    arg_types = {"this": True, "expression": False}
3150
3151
3152class ArraySum(Func):
3153    pass
3154
3155
3156class ArrayUnionAgg(AggFunc):
3157    pass
3158
3159
3160class Avg(AggFunc):
3161    pass
3162
3163
3164class AnyValue(AggFunc):
3165    pass
3166
3167
3168class Case(Func):
3169    arg_types = {"this": False, "ifs": True, "default": False}
3170
3171
3172class Cast(Func):
3173    arg_types = {"this": True, "to": True}
3174
3175    @property
3176    def name(self) -> str:
3177        return self.this.name
3178
3179    @property
3180    def to(self):
3181        return self.args["to"]
3182
3183    @property
3184    def output_name(self):
3185        return self.name
3186
3187    def is_type(self, dtype: DataType.Type) -> bool:
3188        return self.to.is_type(dtype)
3189
3190
3191class Collate(Binary):
3192    pass
3193
3194
3195class TryCast(Cast):
3196    pass
3197
3198
3199class Ceil(Func):
3200    arg_types = {"this": True, "decimals": False}
3201    _sql_names = ["CEIL", "CEILING"]
3202
3203
3204class Coalesce(Func):
3205    arg_types = {"this": True, "expressions": False}
3206    is_var_len_args = True
3207
3208
3209class Concat(Func):
3210    arg_types = {"expressions": True}
3211    is_var_len_args = True
3212
3213
3214class ConcatWs(Concat):
3215    _sql_names = ["CONCAT_WS"]
3216
3217
3218class Count(AggFunc):
3219    arg_types = {"this": False}
3220
3221
3222class CurrentDate(Func):
3223    arg_types = {"this": False}
3224
3225
3226class CurrentDatetime(Func):
3227    arg_types = {"this": False}
3228
3229
3230class CurrentTime(Func):
3231    arg_types = {"this": False}
3232
3233
3234class CurrentTimestamp(Func):
3235    arg_types = {"this": False}
3236
3237
3238class DateAdd(Func, TimeUnit):
3239    arg_types = {"this": True, "expression": True, "unit": False}
3240
3241
3242class DateSub(Func, TimeUnit):
3243    arg_types = {"this": True, "expression": True, "unit": False}
3244
3245
3246class DateDiff(Func, TimeUnit):
3247    arg_types = {"this": True, "expression": True, "unit": False}
3248
3249
3250class DateTrunc(Func):
3251    arg_types = {"unit": True, "this": True, "zone": False}
3252
3253
3254class DatetimeAdd(Func, TimeUnit):
3255    arg_types = {"this": True, "expression": True, "unit": False}
3256
3257
3258class DatetimeSub(Func, TimeUnit):
3259    arg_types = {"this": True, "expression": True, "unit": False}
3260
3261
3262class DatetimeDiff(Func, TimeUnit):
3263    arg_types = {"this": True, "expression": True, "unit": False}
3264
3265
3266class DatetimeTrunc(Func, TimeUnit):
3267    arg_types = {"this": True, "unit": True, "zone": False}
3268
3269
3270class DayOfWeek(Func):
3271    _sql_names = ["DAY_OF_WEEK", "DAYOFWEEK"]
3272
3273
3274class DayOfMonth(Func):
3275    _sql_names = ["DAY_OF_MONTH", "DAYOFMONTH"]
3276
3277
3278class DayOfYear(Func):
3279    _sql_names = ["DAY_OF_YEAR", "DAYOFYEAR"]
3280
3281
3282class WeekOfYear(Func):
3283    _sql_names = ["WEEK_OF_YEAR", "WEEKOFYEAR"]
3284
3285
3286class LastDateOfMonth(Func):
3287    pass
3288
3289
3290class Extract(Func):
3291    arg_types = {"this": True, "expression": True}
3292
3293
3294class TimestampAdd(Func, TimeUnit):
3295    arg_types = {"this": True, "expression": True, "unit": False}
3296
3297
3298class TimestampSub(Func, TimeUnit):
3299    arg_types = {"this": True, "expression": True, "unit": False}
3300
3301
3302class TimestampDiff(Func, TimeUnit):
3303    arg_types = {"this": True, "expression": True, "unit": False}
3304
3305
3306class TimestampTrunc(Func, TimeUnit):
3307    arg_types = {"this": True, "unit": True, "zone": False}
3308
3309
3310class TimeAdd(Func, TimeUnit):
3311    arg_types = {"this": True, "expression": True, "unit": False}
3312
3313
3314class TimeSub(Func, TimeUnit):
3315    arg_types = {"this": True, "expression": True, "unit": False}
3316
3317
3318class TimeDiff(Func, TimeUnit):
3319    arg_types = {"this": True, "expression": True, "unit": False}
3320
3321
3322class TimeTrunc(Func, TimeUnit):
3323    arg_types = {"this": True, "unit": True, "zone": False}
3324
3325
3326class DateFromParts(Func):
3327    _sql_names = ["DATEFROMPARTS"]
3328    arg_types = {"year": True, "month": True, "day": True}
3329
3330
3331class DateStrToDate(Func):
3332    pass
3333
3334
3335class DateToDateStr(Func):
3336    pass
3337
3338
3339class DateToDi(Func):
3340    pass
3341
3342
3343class Day(Func):
3344    pass
3345
3346
3347class Decode(Func):
3348    arg_types = {"this": True, "charset": True, "replace": False}
3349
3350
3351class DiToDate(Func):
3352    pass
3353
3354
3355class Encode(Func):
3356    arg_types = {"this": True, "charset": True}
3357
3358
3359class Exp(Func):
3360    pass
3361
3362
3363class Explode(Func):
3364    pass
3365
3366
3367class Floor(Func):
3368    arg_types = {"this": True, "decimals": False}
3369
3370
3371class Greatest(Func):
3372    arg_types = {"this": True, "expressions": False}
3373    is_var_len_args = True
3374
3375
3376class GroupConcat(Func):
3377    arg_types = {"this": True, "separator": False}
3378
3379
3380class Hex(Func):
3381    pass
3382
3383
3384class If(Func):
3385    arg_types = {"this": True, "true": True, "false": False}
3386
3387
3388class IfNull(Func):
3389    arg_types = {"this": True, "expression": False}
3390    _sql_names = ["IFNULL", "NVL"]
3391
3392
3393class Initcap(Func):
3394    pass
3395
3396
3397class JSONBContains(Binary):
3398    _sql_names = ["JSONB_CONTAINS"]
3399
3400
3401class JSONExtract(Binary, Func):
3402    _sql_names = ["JSON_EXTRACT"]
3403
3404
3405class JSONExtractScalar(JSONExtract):
3406    _sql_names = ["JSON_EXTRACT_SCALAR"]
3407
3408
3409class JSONBExtract(JSONExtract):
3410    _sql_names = ["JSONB_EXTRACT"]
3411
3412
3413class JSONBExtractScalar(JSONExtract):
3414    _sql_names = ["JSONB_EXTRACT_SCALAR"]
3415
3416
3417class Least(Func):
3418    arg_types = {"this": True, "expressions": False}
3419    is_var_len_args = True
3420
3421
3422class Length(Func):
3423    pass
3424
3425
3426class Levenshtein(Func):
3427    arg_types = {
3428        "this": True,
3429        "expression": False,
3430        "ins_cost": False,
3431        "del_cost": False,
3432        "sub_cost": False,
3433    }
3434
3435
3436class Ln(Func):
3437    pass
3438
3439
3440class Log(Func):
3441    arg_types = {"this": True, "expression": False}
3442
3443
3444class Log2(Func):
3445    pass
3446
3447
3448class Log10(Func):
3449    pass
3450
3451
3452class LogicalOr(AggFunc):
3453    _sql_names = ["LOGICAL_OR", "BOOL_OR"]
3454
3455
3456class Lower(Func):
3457    _sql_names = ["LOWER", "LCASE"]
3458
3459
3460class Map(Func):
3461    arg_types = {"keys": False, "values": False}
3462
3463
3464class VarMap(Func):
3465    arg_types = {"keys": True, "values": True}
3466    is_var_len_args = True
3467
3468
3469class Matches(Func):
3470    """Oracle/Snowflake decode.
3471    https://docs.oracle.com/cd/B19306_01/server.102/b14200/functions040.htm
3472    Pattern matching MATCHES(value, search1, result1, ...searchN, resultN, else)
3473    """
3474
3475    arg_types = {"this": True, "expressions": True}
3476    is_var_len_args = True
3477
3478
3479class Max(AggFunc):
3480    arg_types = {"this": True, "expression": False}
3481
3482
3483class Min(AggFunc):
3484    arg_types = {"this": True, "expression": False}
3485
3486
3487class Month(Func):
3488    pass
3489
3490
3491class Nvl2(Func):
3492    arg_types = {"this": True, "true": True, "false": False}
3493
3494
3495class Posexplode(Func):
3496    pass
3497
3498
3499class Pow(Binary, Func):
3500    _sql_names = ["POWER", "POW"]
3501
3502
3503class PercentileCont(AggFunc):
3504    pass
3505
3506
3507class PercentileDisc(AggFunc):
3508    pass
3509
3510
3511class Quantile(AggFunc):
3512    arg_types = {"this": True, "quantile": True}
3513
3514
3515# Clickhouse-specific:
3516# https://clickhouse.com/docs/en/sql-reference/aggregate-functions/reference/quantiles/#quantiles
3517class Quantiles(AggFunc):
3518    arg_types = {"parameters": True, "expressions": True}
3519
3520
3521class QuantileIf(AggFunc):
3522    arg_types = {"parameters": True, "expressions": True}
3523
3524
3525class ApproxQuantile(Quantile):
3526    arg_types = {"this": True, "quantile": True, "accuracy": False, "weight": False}
3527
3528
3529class RangeN(Func):
3530    arg_types = {"this": True, "expressions": True, "each": False}
3531
3532
3533class ReadCSV(Func):
3534    _sql_names = ["READ_CSV"]
3535    is_var_len_args = True
3536    arg_types = {"this": True, "expressions": False}
3537
3538
3539class Reduce(Func):
3540    arg_types = {"this": True, "initial": True, "merge": True, "finish": False}
3541
3542
3543class RegexpExtract(Func):
3544    arg_types = {
3545        "this": True,
3546        "expression": True,
3547        "position": False,
3548        "occurrence": False,
3549        "group": False,
3550    }
3551
3552
3553class RegexpLike(Func):
3554    arg_types = {"this": True, "expression": True, "flag": False}
3555
3556
3557class RegexpILike(Func):
3558    arg_types = {"this": True, "expression": True, "flag": False}
3559
3560
3561class RegexpSplit(Func):
3562    arg_types = {"this": True, "expression": True}
3563
3564
3565class Repeat(Func):
3566    arg_types = {"this": True, "times": True}
3567
3568
3569class Round(Func):
3570    arg_types = {"this": True, "decimals": False}
3571
3572
3573class RowNumber(Func):
3574    arg_types: t.Dict[str, t.Any] = {}
3575
3576
3577class SafeDivide(Func):
3578    arg_types = {"this": True, "expression": True}
3579
3580
3581class SetAgg(AggFunc):
3582    pass
3583
3584
3585class SortArray(Func):
3586    arg_types = {"this": True, "asc": False}
3587
3588
3589class Split(Func):
3590    arg_types = {"this": True, "expression": True, "limit": False}
3591
3592
3593# Start may be omitted in the case of postgres
3594# https://www.postgresql.org/docs/9.1/functions-string.html @ Table 9-6
3595class Substring(Func):
3596    arg_types = {"this": True, "start": False, "length": False}
3597
3598
3599class StrPosition(Func):
3600    arg_types = {
3601        "this": True,
3602        "substr": True,
3603        "position": False,
3604        "instance": False,
3605    }
3606
3607
3608class StrToDate(Func):
3609    arg_types = {"this": True, "format": True}
3610
3611
3612class StrToTime(Func):
3613    arg_types = {"this": True, "format": True}
3614
3615
3616# Spark allows unix_timestamp()
3617# https://spark.apache.org/docs/3.1.3/api/python/reference/api/pyspark.sql.functions.unix_timestamp.html
3618class StrToUnix(Func):
3619    arg_types = {"this": False, "format": False}
3620
3621
3622class NumberToStr(Func):
3623    arg_types = {"this": True, "format": True}
3624
3625
3626class Struct(Func):
3627    arg_types = {"expressions": True}
3628    is_var_len_args = True
3629
3630
3631class StructExtract(Func):
3632    arg_types = {"this": True, "expression": True}
3633
3634
3635class Sum(AggFunc):
3636    pass
3637
3638
3639class Sqrt(Func):
3640    pass
3641
3642
3643class Stddev(AggFunc):
3644    pass
3645
3646
3647class StddevPop(AggFunc):
3648    pass
3649
3650
3651class StddevSamp(AggFunc):
3652    pass
3653
3654
3655class TimeToStr(Func):
3656    arg_types = {"this": True, "format": True}
3657
3658
3659class TimeToTimeStr(Func):
3660    pass
3661
3662
3663class TimeToUnix(Func):
3664    pass
3665
3666
3667class TimeStrToDate(Func):
3668    pass
3669
3670
3671class TimeStrToTime(Func):
3672    pass
3673
3674
3675class TimeStrToUnix(Func):
3676    pass
3677
3678
3679class Trim(Func):
3680    arg_types = {
3681        "this": True,
3682        "expression": False,
3683        "position": False,
3684        "collation": False,
3685    }
3686
3687
3688class TsOrDsAdd(Func, TimeUnit):
3689    arg_types = {"this": True, "expression": True, "unit": False}
3690
3691
3692class TsOrDsToDateStr(Func):
3693    pass
3694
3695
3696class TsOrDsToDate(Func):
3697    arg_types = {"this": True, "format": False}
3698
3699
3700class TsOrDiToDi(Func):
3701    pass
3702
3703
3704class Unhex(Func):
3705    pass
3706
3707
3708class UnixToStr(Func):
3709    arg_types = {"this": True, "format": False}
3710
3711
3712# https://prestodb.io/docs/current/functions/datetime.html
3713# presto has weird zone/hours/minutes
3714class UnixToTime(Func):
3715    arg_types = {"this": True, "scale": False, "zone": False, "hours": False, "minutes": False}
3716
3717    SECONDS = Literal.string("seconds")
3718    MILLIS = Literal.string("millis")
3719    MICROS = Literal.string("micros")
3720
3721
3722class UnixToTimeStr(Func):
3723    pass
3724
3725
3726class Upper(Func):
3727    _sql_names = ["UPPER", "UCASE"]
3728
3729
3730class Variance(AggFunc):
3731    _sql_names = ["VARIANCE", "VARIANCE_SAMP", "VAR_SAMP"]
3732
3733
3734class VariancePop(AggFunc):
3735    _sql_names = ["VARIANCE_POP", "VAR_POP"]
3736
3737
3738class Week(Func):
3739    arg_types = {"this": True, "mode": False}
3740
3741
3742class XMLTable(Func):
3743    arg_types = {"this": True, "passing": False, "columns": False, "by_ref": False}
3744
3745
3746class Year(Func):
3747    pass
3748
3749
3750class Use(Expression):
3751    arg_types = {"this": True, "kind": False}
3752
3753
3754class Merge(Expression):
3755    arg_types = {"this": True, "using": True, "on": True, "expressions": True}
3756
3757
3758class When(Func):
3759    arg_types = {"this": True, "then": True}
3760
3761
3762def _norm_args(expression):
3763    args = {}
3764
3765    for k, arg in expression.args.items():
3766        if isinstance(arg, list):
3767            arg = [_norm_arg(a) for a in arg]
3768            if not arg:
3769                arg = None
3770        else:
3771            arg = _norm_arg(arg)
3772
3773        if arg is not None and arg is not False:
3774            args[k] = arg
3775
3776    return args
3777
3778
3779def _norm_arg(arg):
3780    return arg.lower() if isinstance(arg, str) else arg
3781
3782
3783ALL_FUNCTIONS = subclasses(__name__, Func, (AggFunc, Anonymous, Func))
3784
3785
3786# Helpers
3787def maybe_parse(
3788    sql_or_expression: str | Expression,
3789    *,
3790    into: t.Optional[IntoType] = None,
3791    dialect: DialectType = None,
3792    prefix: t.Optional[str] = None,
3793    copy: bool = False,
3794    **opts,
3795) -> Expression:
3796    """Gracefully handle a possible string or expression.
3797
3798    Example:
3799        >>> maybe_parse("1")
3800        (LITERAL this: 1, is_string: False)
3801        >>> maybe_parse(to_identifier("x"))
3802        (IDENTIFIER this: x, quoted: False)
3803
3804    Args:
3805        sql_or_expression: the SQL code string or an expression
3806        into: the SQLGlot Expression to parse into
3807        dialect: the dialect used to parse the input expressions (in the case that an
3808            input expression is a SQL string).
3809        prefix: a string to prefix the sql with before it gets parsed
3810            (automatically includes a space)
3811        copy: whether or not to copy the expression.
3812        **opts: other options to use to parse the input expressions (again, in the case
3813            that an input expression is a SQL string).
3814
3815    Returns:
3816        Expression: the parsed or given expression.
3817    """
3818    if isinstance(sql_or_expression, Expression):
3819        if copy:
3820            return sql_or_expression.copy()
3821        return sql_or_expression
3822
3823    import sqlglot
3824
3825    sql = str(sql_or_expression)
3826    if prefix:
3827        sql = f"{prefix} {sql}"
3828    return sqlglot.parse_one(sql, read=dialect, into=into, **opts)
3829
3830
3831def _maybe_copy(instance, copy=True):
3832    return instance.copy() if copy else instance
3833
3834
3835def _is_wrong_expression(expression, into):
3836    return isinstance(expression, Expression) and not isinstance(expression, into)
3837
3838
3839def _apply_builder(
3840    expression,
3841    instance,
3842    arg,
3843    copy=True,
3844    prefix=None,
3845    into=None,
3846    dialect=None,
3847    **opts,
3848):
3849    if _is_wrong_expression(expression, into):
3850        expression = into(this=expression)
3851    instance = _maybe_copy(instance, copy)
3852    expression = maybe_parse(
3853        sql_or_expression=expression,
3854        prefix=prefix,
3855        into=into,
3856        dialect=dialect,
3857        **opts,
3858    )
3859    instance.set(arg, expression)
3860    return instance
3861
3862
3863def _apply_child_list_builder(
3864    *expressions,
3865    instance,
3866    arg,
3867    append=True,
3868    copy=True,
3869    prefix=None,
3870    into=None,
3871    dialect=None,
3872    properties=None,
3873    **opts,
3874):
3875    instance = _maybe_copy(instance, copy)
3876    parsed = []
3877    for expression in expressions:
3878        if _is_wrong_expression(expression, into):
3879            expression = into(expressions=[expression])
3880        expression = maybe_parse(
3881            expression,
3882            into=into,
3883            dialect=dialect,
3884            prefix=prefix,
3885            **opts,
3886        )
3887        parsed.extend(expression.expressions)
3888
3889    existing = instance.args.get(arg)
3890    if append and existing:
3891        parsed = existing.expressions + parsed
3892
3893    child = into(expressions=parsed)
3894    for k, v in (properties or {}).items():
3895        child.set(k, v)
3896    instance.set(arg, child)
3897    return instance
3898
3899
3900def _apply_list_builder(
3901    *expressions,
3902    instance,
3903    arg,
3904    append=True,
3905    copy=True,
3906    prefix=None,
3907    into=None,
3908    dialect=None,
3909    **opts,
3910):
3911    inst = _maybe_copy(instance, copy)
3912
3913    expressions = [
3914        maybe_parse(
3915            sql_or_expression=expression,
3916            into=into,
3917            prefix=prefix,
3918            dialect=dialect,
3919            **opts,
3920        )
3921        for expression in expressions
3922    ]
3923
3924    existing_expressions = inst.args.get(arg)
3925    if append and existing_expressions:
3926        expressions = existing_expressions + expressions
3927
3928    inst.set(arg, expressions)
3929    return inst
3930
3931
3932def _apply_conjunction_builder(
3933    *expressions,
3934    instance,
3935    arg,
3936    into=None,
3937    append=True,
3938    copy=True,
3939    dialect=None,
3940    **opts,
3941):
3942    expressions = [exp for exp in expressions if exp is not None and exp != ""]
3943    if not expressions:
3944        return instance
3945
3946    inst = _maybe_copy(instance, copy)
3947
3948    existing = inst.args.get(arg)
3949    if append and existing is not None:
3950        expressions = [existing.this if into else existing] + list(expressions)
3951
3952    node = and_(*expressions, dialect=dialect, **opts)
3953
3954    inst.set(arg, into(this=node) if into else node)
3955    return inst
3956
3957
3958def _combine(expressions, operator, dialect=None, **opts):
3959    expressions = [condition(expression, dialect=dialect, **opts) for expression in expressions]
3960    this = expressions[0]
3961    if expressions[1:]:
3962        this = _wrap_operator(this)
3963    for expression in expressions[1:]:
3964        this = operator(this=this, expression=_wrap_operator(expression))
3965    return this
3966
3967
3968def _wrap_operator(expression):
3969    if isinstance(expression, (And, Or, Not)):
3970        expression = Paren(this=expression)
3971    return expression
3972
3973
3974def union(left, right, distinct=True, dialect=None, **opts):
3975    """
3976    Initializes a syntax tree from one UNION expression.
3977
3978    Example:
3979        >>> union("SELECT * FROM foo", "SELECT * FROM bla").sql()
3980        'SELECT * FROM foo UNION SELECT * FROM bla'
3981
3982    Args:
3983        left (str | Expression): the SQL code string corresponding to the left-hand side.
3984            If an `Expression` instance is passed, it will be used as-is.
3985        right (str | Expression): the SQL code string corresponding to the right-hand side.
3986            If an `Expression` instance is passed, it will be used as-is.
3987        distinct (bool): set the DISTINCT flag if and only if this is true.
3988        dialect (str): the dialect used to parse the input expression.
3989        opts (kwargs): other options to use to parse the input expressions.
3990    Returns:
3991        Union: the syntax tree for the UNION expression.
3992    """
3993    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
3994    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
3995
3996    return Union(this=left, expression=right, distinct=distinct)
3997
3998
3999def intersect(left, right, distinct=True, dialect=None, **opts):
4000    """
4001    Initializes a syntax tree from one INTERSECT expression.
4002
4003    Example:
4004        >>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql()
4005        'SELECT * FROM foo INTERSECT SELECT * FROM bla'
4006
4007    Args:
4008        left (str | Expression): the SQL code string corresponding to the left-hand side.
4009            If an `Expression` instance is passed, it will be used as-is.
4010        right (str | Expression): the SQL code string corresponding to the right-hand side.
4011            If an `Expression` instance is passed, it will be used as-is.
4012        distinct (bool): set the DISTINCT flag if and only if this is true.
4013        dialect (str): the dialect used to parse the input expression.
4014        opts (kwargs): other options to use to parse the input expressions.
4015    Returns:
4016        Intersect: the syntax tree for the INTERSECT expression.
4017    """
4018    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
4019    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
4020
4021    return Intersect(this=left, expression=right, distinct=distinct)
4022
4023
4024def except_(left, right, distinct=True, dialect=None, **opts):
4025    """
4026    Initializes a syntax tree from one EXCEPT expression.
4027
4028    Example:
4029        >>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql()
4030        'SELECT * FROM foo EXCEPT SELECT * FROM bla'
4031
4032    Args:
4033        left (str | Expression): the SQL code string corresponding to the left-hand side.
4034            If an `Expression` instance is passed, it will be used as-is.
4035        right (str | Expression): the SQL code string corresponding to the right-hand side.
4036            If an `Expression` instance is passed, it will be used as-is.
4037        distinct (bool): set the DISTINCT flag if and only if this is true.
4038        dialect (str): the dialect used to parse the input expression.
4039        opts (kwargs): other options to use to parse the input expressions.
4040    Returns:
4041        Except: the syntax tree for the EXCEPT statement.
4042    """
4043    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
4044    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
4045
4046    return Except(this=left, expression=right, distinct=distinct)
4047
4048
4049def select(*expressions: str | Expression, dialect: DialectType = None, **opts) -> Select:
4050    """
4051    Initializes a syntax tree from one or multiple SELECT expressions.
4052
4053    Example:
4054        >>> select("col1", "col2").from_("tbl").sql()
4055        'SELECT col1, col2 FROM tbl'
4056
4057    Args:
4058        *expressions: the SQL code string to parse as the expressions of a
4059            SELECT statement. If an Expression instance is passed, this is used as-is.
4060        dialect: the dialect used to parse the input expressions (in the case that an
4061            input expression is a SQL string).
4062        **opts: other options to use to parse the input expressions (again, in the case
4063            that an input expression is a SQL string).
4064
4065    Returns:
4066        Select: the syntax tree for the SELECT statement.
4067    """
4068    return Select().select(*expressions, dialect=dialect, **opts)
4069
4070
4071def from_(*expressions, dialect=None, **opts) -> Select:
4072    """
4073    Initializes a syntax tree from a FROM expression.
4074
4075    Example:
4076        >>> from_("tbl").select("col1", "col2").sql()
4077        'SELECT col1, col2 FROM tbl'
4078
4079    Args:
4080        *expressions (str | Expression): the SQL code string to parse as the FROM expressions of a
4081            SELECT statement. If an Expression instance is passed, this is used as-is.
4082        dialect (str): the dialect used to parse the input expression (in the case that the
4083            input expression is a SQL string).
4084        **opts: other options to use to parse the input expressions (again, in the case
4085            that the input expression is a SQL string).
4086
4087    Returns:
4088        Select: the syntax tree for the SELECT statement.
4089    """
4090    return Select().from_(*expressions, dialect=dialect, **opts)
4091
4092
4093def update(table, properties, where=None, from_=None, dialect=None, **opts) -> Update:
4094    """
4095    Creates an update statement.
4096
4097    Example:
4098        >>> update("my_table", {"x": 1, "y": "2", "z": None}, from_="baz", where="id > 1").sql()
4099        "UPDATE my_table SET x = 1, y = '2', z = NULL FROM baz WHERE id > 1"
4100
4101    Args:
4102        *properties (Dict[str, Any]): dictionary of properties to set which are
4103            auto converted to sql objects eg None -> NULL
4104        where (str): sql conditional parsed into a WHERE statement
4105        from_ (str): sql statement parsed into a FROM statement
4106        dialect (str): the dialect used to parse the input expressions.
4107        **opts: other options to use to parse the input expressions.
4108
4109    Returns:
4110        Update: the syntax tree for the UPDATE statement.
4111    """
4112    update = Update(this=maybe_parse(table, into=Table, dialect=dialect))
4113    update.set(
4114        "expressions",
4115        [
4116            EQ(this=maybe_parse(k, dialect=dialect, **opts), expression=convert(v))
4117            for k, v in properties.items()
4118        ],
4119    )
4120    if from_:
4121        update.set(
4122            "from",
4123            maybe_parse(from_, into=From, dialect=dialect, prefix="FROM", **opts),
4124        )
4125    if isinstance(where, Condition):
4126        where = Where(this=where)
4127    if where:
4128        update.set(
4129            "where",
4130            maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts),
4131        )
4132    return update
4133
4134
4135def delete(table, where=None, dialect=None, **opts) -> Delete:
4136    """
4137    Builds a delete statement.
4138
4139    Example:
4140        >>> delete("my_table", where="id > 1").sql()
4141        'DELETE FROM my_table WHERE id > 1'
4142
4143    Args:
4144        where (str|Condition): sql conditional parsed into a WHERE statement
4145        dialect (str): the dialect used to parse the input expressions.
4146        **opts: other options to use to parse the input expressions.
4147
4148    Returns:
4149        Delete: the syntax tree for the DELETE statement.
4150    """
4151    return Delete(
4152        this=maybe_parse(table, into=Table, dialect=dialect, **opts),
4153        where=Where(this=where)
4154        if isinstance(where, Condition)
4155        else maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts),
4156    )
4157
4158
4159def condition(expression, dialect=None, **opts) -> Condition:
4160    """
4161    Initialize a logical condition expression.
4162
4163    Example:
4164        >>> condition("x=1").sql()
4165        'x = 1'
4166
4167        This is helpful for composing larger logical syntax trees:
4168        >>> where = condition("x=1")
4169        >>> where = where.and_("y=1")
4170        >>> Select().from_("tbl").select("*").where(where).sql()
4171        'SELECT * FROM tbl WHERE x = 1 AND y = 1'
4172
4173    Args:
4174        *expression (str | Expression): the SQL code string to parse.
4175            If an Expression instance is passed, this is used as-is.
4176        dialect (str): the dialect used to parse the input expression (in the case that the
4177            input expression is a SQL string).
4178        **opts: other options to use to parse the input expressions (again, in the case
4179            that the input expression is a SQL string).
4180
4181    Returns:
4182        Condition: the expression
4183    """
4184    return maybe_parse(  # type: ignore
4185        expression,
4186        into=Condition,
4187        dialect=dialect,
4188        **opts,
4189    )
4190
4191
4192def and_(*expressions, dialect=None, **opts) -> And:
4193    """
4194    Combine multiple conditions with an AND logical operator.
4195
4196    Example:
4197        >>> and_("x=1", and_("y=1", "z=1")).sql()
4198        'x = 1 AND (y = 1 AND z = 1)'
4199
4200    Args:
4201        *expressions (str | Expression): the SQL code strings to parse.
4202            If an Expression instance is passed, this is used as-is.
4203        dialect (str): the dialect used to parse the input expression.
4204        **opts: other options to use to parse the input expressions.
4205
4206    Returns:
4207        And: the new condition
4208    """
4209    return _combine(expressions, And, dialect, **opts)
4210
4211
4212def or_(*expressions, dialect=None, **opts) -> Or:
4213    """
4214    Combine multiple conditions with an OR logical operator.
4215
4216    Example:
4217        >>> or_("x=1", or_("y=1", "z=1")).sql()
4218        'x = 1 OR (y = 1 OR z = 1)'
4219
4220    Args:
4221        *expressions (str | Expression): the SQL code strings to parse.
4222            If an Expression instance is passed, this is used as-is.
4223        dialect (str): the dialect used to parse the input expression.
4224        **opts: other options to use to parse the input expressions.
4225
4226    Returns:
4227        Or: the new condition
4228    """
4229    return _combine(expressions, Or, dialect, **opts)
4230
4231
4232def not_(expression, dialect=None, **opts) -> Not:
4233    """
4234    Wrap a condition with a NOT operator.
4235
4236    Example:
4237        >>> not_("this_suit='black'").sql()
4238        "NOT this_suit = 'black'"
4239
4240    Args:
4241        expression (str | Expression): the SQL code strings to parse.
4242            If an Expression instance is passed, this is used as-is.
4243        dialect (str): the dialect used to parse the input expression.
4244        **opts: other options to use to parse the input expressions.
4245
4246    Returns:
4247        Not: the new condition
4248    """
4249    this = condition(
4250        expression,
4251        dialect=dialect,
4252        **opts,
4253    )
4254    return Not(this=_wrap_operator(this))
4255
4256
4257def paren(expression) -> Paren:
4258    return Paren(this=expression)
4259
4260
4261SAFE_IDENTIFIER_RE = re.compile(r"^[_a-zA-Z][\w]*$")
4262
4263
4264@t.overload
4265def to_identifier(name: None, quoted: t.Optional[bool] = None) -> None:
4266    ...
4267
4268
4269@t.overload
4270def to_identifier(name: str | Identifier, quoted: t.Optional[bool] = None) -> Identifier:
4271    ...
4272
4273
4274def to_identifier(name, quoted=None):
4275    """Builds an identifier.
4276
4277    Args:
4278        name: The name to turn into an identifier.
4279        quoted: Whether or not force quote the identifier.
4280
4281    Returns:
4282        The identifier ast node.
4283    """
4284
4285    if name is None:
4286        return None
4287
4288    if isinstance(name, Identifier):
4289        identifier = name
4290    elif isinstance(name, str):
4291        identifier = Identifier(
4292            this=name,
4293            quoted=not re.match(SAFE_IDENTIFIER_RE, name) if quoted is None else quoted,
4294        )
4295    else:
4296        raise ValueError(f"Name needs to be a string or an Identifier, got: {name.__class__}")
4297    return identifier
4298
4299
4300INTERVAL_STRING_RE = re.compile(r"\s*([0-9]+)\s*([a-zA-Z]+)\s*")
4301
4302
4303def to_interval(interval: str | Literal) -> Interval:
4304    """Builds an interval expression from a string like '1 day' or '5 months'."""
4305    if isinstance(interval, Literal):
4306        if not interval.is_string:
4307            raise ValueError("Invalid interval string.")
4308
4309        interval = interval.this
4310
4311    interval_parts = INTERVAL_STRING_RE.match(interval)  # type: ignore
4312
4313    if not interval_parts:
4314        raise ValueError("Invalid interval string.")
4315
4316    return Interval(
4317        this=Literal.string(interval_parts.group(1)),
4318        unit=Var(this=interval_parts.group(2)),
4319    )
4320
4321
4322@t.overload
4323def to_table(sql_path: str | Table, **kwargs) -> Table:
4324    ...
4325
4326
4327@t.overload
4328def to_table(sql_path: None, **kwargs) -> None:
4329    ...
4330
4331
4332def to_table(sql_path: t.Optional[str | Table], **kwargs) -> t.Optional[Table]:
4333    """
4334    Create a table expression from a `[catalog].[schema].[table]` sql path. Catalog and schema are optional.
4335    If a table is passed in then that table is returned.
4336
4337    Args:
4338        sql_path: a `[catalog].[schema].[table]` string.
4339
4340    Returns:
4341        A table expression.
4342    """
4343    if sql_path is None or isinstance(sql_path, Table):
4344        return sql_path
4345    if not isinstance(sql_path, str):
4346        raise ValueError(f"Invalid type provided for a table: {type(sql_path)}")
4347
4348    catalog, db, table_name = (to_identifier(x) for x in split_num_words(sql_path, ".", 3))
4349    return Table(this=table_name, db=db, catalog=catalog, **kwargs)
4350
4351
4352def to_column(sql_path: str | Column, **kwargs) -> Column:
4353    """
4354    Create a column from a `[table].[column]` sql path. Schema is optional.
4355
4356    If a column is passed in then that column is returned.
4357
4358    Args:
4359        sql_path: `[table].[column]` string
4360    Returns:
4361        Table: A column expression
4362    """
4363    if sql_path is None or isinstance(sql_path, Column):
4364        return sql_path
4365    if not isinstance(sql_path, str):
4366        raise ValueError(f"Invalid type provided for column: {type(sql_path)}")
4367    table_name, column_name = (to_identifier(x) for x in split_num_words(sql_path, ".", 2))
4368    return Column(this=column_name, table=table_name, **kwargs)
4369
4370
4371def alias_(
4372    expression: str | Expression,
4373    alias: str | Identifier,
4374    table: bool | t.Sequence[str | Identifier] = False,
4375    quoted: t.Optional[bool] = None,
4376    dialect: DialectType = None,
4377    **opts,
4378):
4379    """Create an Alias expression.
4380
4381    Example:
4382        >>> alias_('foo', 'bar').sql()
4383        'foo AS bar'
4384
4385        >>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql()
4386        '(SELECT 1, 2) AS bar(a, b)'
4387
4388    Args:
4389        expression: the SQL code strings to parse.
4390            If an Expression instance is passed, this is used as-is.
4391        alias: the alias name to use. If the name has
4392            special characters it is quoted.
4393        table: Whether or not to create a table alias, can also be a list of columns.
4394        quoted: whether or not to quote the alias
4395        dialect: the dialect used to parse the input expression.
4396        **opts: other options to use to parse the input expressions.
4397
4398    Returns:
4399        Alias: the aliased expression
4400    """
4401    exp = maybe_parse(expression, dialect=dialect, **opts)
4402    alias = to_identifier(alias, quoted=quoted)
4403
4404    if table:
4405        table_alias = TableAlias(this=alias)
4406        exp.set("alias", table_alias)
4407
4408        if not isinstance(table, bool):
4409            for column in table:
4410                table_alias.append("columns", to_identifier(column, quoted=quoted))
4411
4412        return exp
4413
4414    # We don't set the "alias" arg for Window expressions, because that would add an IDENTIFIER node in
4415    # the AST, representing a "named_window" [1] construct (eg. bigquery). What we want is an ALIAS node
4416    # for the complete Window expression.
4417    #
4418    # [1]: https://cloud.google.com/bigquery/docs/reference/standard-sql/window-function-calls
4419
4420    if "alias" in exp.arg_types and not isinstance(exp, Window):
4421        exp = exp.copy()
4422        exp.set("alias", alias)
4423        return exp
4424    return Alias(this=exp, alias=alias)
4425
4426
4427def subquery(expression, alias=None, dialect=None, **opts):
4428    """
4429    Build a subquery expression.
4430
4431    Example:
4432        >>> subquery('select x from tbl', 'bar').select('x').sql()
4433        'SELECT x FROM (SELECT x FROM tbl) AS bar'
4434
4435    Args:
4436        expression (str | Expression): the SQL code strings to parse.
4437            If an Expression instance is passed, this is used as-is.
4438        alias (str | Expression): the alias name to use.
4439        dialect (str): the dialect used to parse the input expression.
4440        **opts: other options to use to parse the input expressions.
4441
4442    Returns:
4443        Select: a new select with the subquery expression included
4444    """
4445
4446    expression = maybe_parse(expression, dialect=dialect, **opts).subquery(alias)
4447    return Select().from_(expression, dialect=dialect, **opts)
4448
4449
4450def column(
4451    col: str | Identifier,
4452    table: t.Optional[str | Identifier] = None,
4453    schema: t.Optional[str | Identifier] = None,
4454    quoted: t.Optional[bool] = None,
4455) -> Column:
4456    """
4457    Build a Column.
4458
4459    Args:
4460        col: column name
4461        table: table name
4462        schema: schema name
4463        quoted: whether or not to force quote each part
4464    Returns:
4465        Column: column instance
4466    """
4467    return Column(
4468        this=to_identifier(col, quoted=quoted),
4469        table=to_identifier(table, quoted=quoted),
4470        schema=to_identifier(schema, quoted=quoted),
4471    )
4472
4473
4474def cast(expression: str | Expression, to: str | DataType | DataType.Type, **opts) -> Cast:
4475    """Cast an expression to a data type.
4476
4477    Example:
4478        >>> cast('x + 1', 'int').sql()
4479        'CAST(x + 1 AS INT)'
4480
4481    Args:
4482        expression: The expression to cast.
4483        to: The datatype to cast to.
4484
4485    Returns:
4486        A cast node.
4487    """
4488    expression = maybe_parse(expression, **opts)
4489    return Cast(this=expression, to=DataType.build(to, **opts))
4490
4491
4492def table_(table, db=None, catalog=None, quoted=None, alias=None) -> Table:
4493    """Build a Table.
4494
4495    Args:
4496        table (str | Expression): column name
4497        db (str | Expression): db name
4498        catalog (str | Expression): catalog name
4499
4500    Returns:
4501        Table: table instance
4502    """
4503    return Table(
4504        this=to_identifier(table, quoted=quoted),
4505        db=to_identifier(db, quoted=quoted),
4506        catalog=to_identifier(catalog, quoted=quoted),
4507        alias=TableAlias(this=to_identifier(alias)) if alias else None,
4508    )
4509
4510
4511def values(
4512    values: t.Iterable[t.Tuple[t.Any, ...]],
4513    alias: t.Optional[str] = None,
4514    columns: t.Optional[t.Iterable[str] | t.Dict[str, DataType]] = None,
4515) -> Values:
4516    """Build VALUES statement.
4517
4518    Example:
4519        >>> values([(1, '2')]).sql()
4520        "VALUES (1, '2')"
4521
4522    Args:
4523        values: values statements that will be converted to SQL
4524        alias: optional alias
4525        columns: Optional list of ordered column names or ordered dictionary of column names to types.
4526         If either are provided then an alias is also required.
4527         If a dictionary is provided then the first column of the values will be casted to the expected type
4528         in order to help with type inference.
4529
4530    Returns:
4531        Values: the Values expression object
4532    """
4533    if columns and not alias:
4534        raise ValueError("Alias is required when providing columns")
4535    table_alias = (
4536        TableAlias(this=to_identifier(alias), columns=[to_identifier(x) for x in columns])
4537        if columns
4538        else TableAlias(this=to_identifier(alias) if alias else None)
4539    )
4540    expressions = [convert(tup) for tup in values]
4541    if columns and isinstance(columns, dict):
4542        types = list(columns.values())
4543        expressions[0].set(
4544            "expressions",
4545            [cast(x, types[i]) for i, x in enumerate(expressions[0].expressions)],
4546        )
4547    return Values(
4548        expressions=expressions,
4549        alias=table_alias,
4550    )
4551
4552
4553def var(name: t.Optional[str | Expression]) -> Var:
4554    """Build a SQL variable.
4555
4556    Example:
4557        >>> repr(var('x'))
4558        '(VAR this: x)'
4559
4560        >>> repr(var(column('x', table='y')))
4561        '(VAR this: x)'
4562
4563    Args:
4564        name: The name of the var or an expression who's name will become the var.
4565
4566    Returns:
4567        The new variable node.
4568    """
4569    if not name:
4570        raise ValueError(f"Cannot convert empty name into var.")
4571
4572    if isinstance(name, Expression):
4573        name = name.name
4574    return Var(this=name)
4575
4576
4577def rename_table(old_name: str | Table, new_name: str | Table) -> AlterTable:
4578    """Build ALTER TABLE... RENAME... expression
4579
4580    Args:
4581        old_name: The old name of the table
4582        new_name: The new name of the table
4583
4584    Returns:
4585        Alter table expression
4586    """
4587    old_table = to_table(old_name)
4588    new_table = to_table(new_name)
4589    return AlterTable(
4590        this=old_table,
4591        actions=[
4592            RenameTable(this=new_table),
4593        ],
4594    )
4595
4596
4597def convert(value) -> Expression:
4598    """Convert a python value into an expression object.
4599
4600    Raises an error if a conversion is not possible.
4601
4602    Args:
4603        value (Any): a python object
4604
4605    Returns:
4606        Expression: the equivalent expression object
4607    """
4608    if isinstance(value, Expression):
4609        return value
4610    if value is None:
4611        return NULL
4612    if isinstance(value, bool):
4613        return Boolean(this=value)
4614    if isinstance(value, str):
4615        return Literal.string(value)
4616    if isinstance(value, float) and math.isnan(value):
4617        return NULL
4618    if isinstance(value, numbers.Number):
4619        return Literal.number(value)
4620    if isinstance(value, tuple):
4621        return Tuple(expressions=[convert(v) for v in value])
4622    if isinstance(value, list):
4623        return Array(expressions=[convert(v) for v in value])
4624    if isinstance(value, dict):
4625        return Map(
4626            keys=[convert(k) for k in value],
4627            values=[convert(v) for v in value.values()],
4628        )
4629    if isinstance(value, datetime.datetime):
4630        datetime_literal = Literal.string(
4631            (value if value.tzinfo else value.replace(tzinfo=datetime.timezone.utc)).isoformat()
4632        )
4633        return TimeStrToTime(this=datetime_literal)
4634    if isinstance(value, datetime.date):
4635        date_literal = Literal.string(value.strftime("%Y-%m-%d"))
4636        return DateStrToDate(this=date_literal)
4637    raise ValueError(f"Cannot convert {value}")
4638
4639
4640def replace_children(expression, fun):
4641    """
4642    Replace children of an expression with the result of a lambda fun(child) -> exp.
4643    """
4644    for k, v in expression.args.items():
4645        is_list_arg = isinstance(v, list)
4646
4647        child_nodes = v if is_list_arg else [v]
4648        new_child_nodes = []
4649
4650        for cn in child_nodes:
4651            if isinstance(cn, Expression):
4652                for child_node in ensure_collection(fun(cn)):
4653                    new_child_nodes.append(child_node)
4654                    child_node.parent = expression
4655                    child_node.arg_key = k
4656            else:
4657                new_child_nodes.append(cn)
4658
4659        expression.args[k] = new_child_nodes if is_list_arg else seq_get(new_child_nodes, 0)
4660
4661
4662def column_table_names(expression):
4663    """
4664    Return all table names referenced through columns in an expression.
4665
4666    Example:
4667        >>> import sqlglot
4668        >>> column_table_names(sqlglot.parse_one("a.b AND c.d AND c.e"))
4669        ['c', 'a']
4670
4671    Args:
4672        expression (sqlglot.Expression): expression to find table names
4673
4674    Returns:
4675        list: A list of unique names
4676    """
4677    return list(dict.fromkeys(column.table for column in expression.find_all(Column)))
4678
4679
4680def table_name(table) -> str:
4681    """Get the full name of a table as a string.
4682
4683    Args:
4684        table (exp.Table | str): table expression node or string.
4685
4686    Examples:
4687        >>> from sqlglot import exp, parse_one
4688        >>> table_name(parse_one("select * from a.b.c").find(exp.Table))
4689        'a.b.c'
4690
4691    Returns:
4692        The table name.
4693    """
4694
4695    table = maybe_parse(table, into=Table)
4696
4697    if not table:
4698        raise ValueError(f"Cannot parse {table}")
4699
4700    return ".".join(
4701        part
4702        for part in (
4703            table.text("catalog"),
4704            table.text("db"),
4705            table.name,
4706        )
4707        if part
4708    )
4709
4710
4711def replace_tables(expression, mapping):
4712    """Replace all tables in expression according to the mapping.
4713
4714    Args:
4715        expression (sqlglot.Expression): expression node to be transformed and replaced.
4716        mapping (Dict[str, str]): mapping of table names.
4717
4718    Examples:
4719        >>> from sqlglot import exp, parse_one
4720        >>> replace_tables(parse_one("select * from a.b"), {"a.b": "c"}).sql()
4721        'SELECT * FROM c'
4722
4723    Returns:
4724        The mapped expression.
4725    """
4726
4727    def _replace_tables(node):
4728        if isinstance(node, Table):
4729            new_name = mapping.get(table_name(node))
4730            if new_name:
4731                return to_table(
4732                    new_name,
4733                    **{k: v for k, v in node.args.items() if k not in ("this", "db", "catalog")},
4734                )
4735        return node
4736
4737    return expression.transform(_replace_tables)
4738
4739
4740def replace_placeholders(expression, *args, **kwargs):
4741    """Replace placeholders in an expression.
4742
4743    Args:
4744        expression (sqlglot.Expression): expression node to be transformed and replaced.
4745        args: positional names that will substitute unnamed placeholders in the given order.
4746        kwargs: keyword arguments that will substitute named placeholders.
4747
4748    Examples:
4749        >>> from sqlglot import exp, parse_one
4750        >>> replace_placeholders(
4751        ...     parse_one("select * from :tbl where ? = ?"), "a", "b", tbl="foo"
4752        ... ).sql()
4753        'SELECT * FROM foo WHERE a = b'
4754
4755    Returns:
4756        The mapped expression.
4757    """
4758
4759    def _replace_placeholders(node, args, **kwargs):
4760        if isinstance(node, Placeholder):
4761            if node.name:
4762                new_name = kwargs.get(node.name)
4763                if new_name:
4764                    return to_identifier(new_name)
4765            else:
4766                try:
4767                    return to_identifier(next(args))
4768                except StopIteration:
4769                    pass
4770        return node
4771
4772    return expression.transform(_replace_placeholders, iter(args), **kwargs)
4773
4774
4775def expand(expression: Expression, sources: t.Dict[str, Subqueryable], copy=True) -> Expression:
4776    """Transforms an expression by expanding all referenced sources into subqueries.
4777
4778    Examples:
4779        >>> from sqlglot import parse_one
4780        >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y")}).sql()
4781        'SELECT * FROM (SELECT * FROM y) AS z /* source: x */'
4782
4783    Args:
4784        expression: The expression to expand.
4785        sources: A dictionary of name to Subqueryables.
4786        copy: Whether or not to copy the expression during transformation. Defaults to True.
4787
4788    Returns:
4789        The transformed expression.
4790    """
4791
4792    def _expand(node: Expression):
4793        if isinstance(node, Table):
4794            name = table_name(node)
4795            source = sources.get(name)
4796            if source:
4797                subquery = source.subquery(node.alias or name)
4798                subquery.comments = [f"source: {name}"]
4799                return subquery
4800        return node
4801
4802    return expression.transform(_expand, copy=copy)
4803
4804
4805def func(name: str, *args, dialect: DialectType = None, **kwargs) -> Func:
4806    """
4807    Returns a Func expression.
4808
4809    Examples:
4810        >>> func("abs", 5).sql()
4811        'ABS(5)'
4812
4813        >>> func("cast", this=5, to=DataType.build("DOUBLE")).sql()
4814        'CAST(5 AS DOUBLE)'
4815
4816    Args:
4817        name: the name of the function to build.
4818        args: the args used to instantiate the function of interest.
4819        dialect: the source dialect.
4820        kwargs: the kwargs used to instantiate the function of interest.
4821
4822    Note:
4823        The arguments `args` and `kwargs` are mutually exclusive.
4824
4825    Returns:
4826        An instance of the function of interest, or an anonymous function, if `name` doesn't
4827        correspond to an existing `sqlglot.expressions.Func` class.
4828    """
4829    if args and kwargs:
4830        raise ValueError("Can't use both args and kwargs to instantiate a function.")
4831
4832    from sqlglot.dialects.dialect import Dialect
4833
4834    args = tuple(convert(arg) for arg in args)
4835    kwargs = {key: convert(value) for key, value in kwargs.items()}
4836
4837    parser = Dialect.get_or_raise(dialect)().parser()
4838    from_args_list = parser.FUNCTIONS.get(name.upper())
4839
4840    if from_args_list:
4841        function = from_args_list(args) if args else from_args_list.__self__(**kwargs)  # type: ignore
4842    else:
4843        kwargs = kwargs or {"expressions": args}
4844        function = Anonymous(this=name, **kwargs)
4845
4846    for error_message in function.error_messages(args):
4847        raise ValueError(error_message)
4848
4849    return function
4850
4851
4852def true():
4853    """
4854    Returns a true Boolean expression.
4855    """
4856    return Boolean(this=True)
4857
4858
4859def false():
4860    """
4861    Returns a false Boolean expression.
4862    """
4863    return Boolean(this=False)
4864
4865
4866def null():
4867    """
4868    Returns a Null expression.
4869    """
4870    return Null()
4871
4872
4873# TODO: deprecate this
4874TRUE = Boolean(this=True)
4875FALSE = Boolean(this=False)
4876NULL = Null()
class Expression:
 56class Expression(metaclass=_Expression):
 57    """
 58    The base class for all expressions in a syntax tree. Each Expression encapsulates any necessary
 59    context, such as its child expressions, their names (arg keys), and whether a given child expression
 60    is optional or not.
 61
 62    Attributes:
 63        key: a unique key for each class in the Expression hierarchy. This is useful for hashing
 64            and representing expressions as strings.
 65        arg_types: determines what arguments (child nodes) are supported by an expression. It
 66            maps arg keys to booleans that indicate whether the corresponding args are optional.
 67
 68    Example:
 69        >>> class Foo(Expression):
 70        ...     arg_types = {"this": True, "expression": False}
 71
 72        The above definition informs us that Foo is an Expression that requires an argument called
 73        "this" and may also optionally receive an argument called "expression".
 74
 75    Args:
 76        args: a mapping used for retrieving the arguments of an expression, given their arg keys.
 77        parent: a reference to the parent expression (or None, in case of root expressions).
 78        arg_key: the arg key an expression is associated with, i.e. the name its parent expression
 79            uses to refer to it.
 80        comments: a list of comments that are associated with a given expression. This is used in
 81            order to preserve comments when transpiling SQL code.
 82        _type: the `sqlglot.expressions.DataType` type of an expression. This is inferred by the
 83            optimizer, in order to enable some transformations that require type information.
 84    """
 85
 86    key = "expression"
 87    arg_types = {"this": True}
 88    __slots__ = ("args", "parent", "arg_key", "comments", "_type", "_meta")
 89
 90    def __init__(self, **args: t.Any):
 91        self.args: t.Dict[str, t.Any] = args
 92        self.parent: t.Optional[Expression] = None
 93        self.arg_key: t.Optional[str] = None
 94        self.comments: t.Optional[t.List[str]] = None
 95        self._type: t.Optional[DataType] = None
 96        self._meta: t.Optional[t.Dict[str, t.Any]] = None
 97
 98        for arg_key, value in self.args.items():
 99            self._set_parent(arg_key, value)
100
101    def __eq__(self, other) -> bool:
102        return type(self) is type(other) and _norm_args(self) == _norm_args(other)
103
104    def __hash__(self) -> int:
105        return hash(
106            (
107                self.key,
108                tuple(
109                    (k, tuple(v) if isinstance(v, list) else v) for k, v in _norm_args(self).items()
110                ),
111            )
112        )
113
114    @property
115    def this(self):
116        """
117        Retrieves the argument with key "this".
118        """
119        return self.args.get("this")
120
121    @property
122    def expression(self):
123        """
124        Retrieves the argument with key "expression".
125        """
126        return self.args.get("expression")
127
128    @property
129    def expressions(self):
130        """
131        Retrieves the argument with key "expressions".
132        """
133        return self.args.get("expressions") or []
134
135    def text(self, key) -> str:
136        """
137        Returns a textual representation of the argument corresponding to "key". This can only be used
138        for args that are strings or leaf Expression instances, such as identifiers and literals.
139        """
140        field = self.args.get(key)
141        if isinstance(field, str):
142            return field
143        if isinstance(field, (Identifier, Literal, Var)):
144            return field.this
145        if isinstance(field, (Star, Null)):
146            return field.name
147        return ""
148
149    @property
150    def is_string(self) -> bool:
151        """
152        Checks whether a Literal expression is a string.
153        """
154        return isinstance(self, Literal) and self.args["is_string"]
155
156    @property
157    def is_number(self) -> bool:
158        """
159        Checks whether a Literal expression is a number.
160        """
161        return isinstance(self, Literal) and not self.args["is_string"]
162
163    @property
164    def is_int(self) -> bool:
165        """
166        Checks whether a Literal expression is an integer.
167        """
168        if self.is_number:
169            try:
170                int(self.name)
171                return True
172            except ValueError:
173                pass
174        return False
175
176    @property
177    def is_star(self) -> bool:
178        """Checks whether an expression is a star."""
179        return isinstance(self, Star) or (isinstance(self, Column) and isinstance(self.this, Star))
180
181    @property
182    def alias(self) -> str:
183        """
184        Returns the alias of the expression, or an empty string if it's not aliased.
185        """
186        if isinstance(self.args.get("alias"), TableAlias):
187            return self.args["alias"].name
188        return self.text("alias")
189
190    @property
191    def name(self) -> str:
192        return self.text("this")
193
194    @property
195    def alias_or_name(self):
196        return self.alias or self.name
197
198    @property
199    def output_name(self):
200        """
201        Name of the output column if this expression is a selection.
202
203        If the Expression has no output name, an empty string is returned.
204
205        Example:
206            >>> from sqlglot import parse_one
207            >>> parse_one("SELECT a").expressions[0].output_name
208            'a'
209            >>> parse_one("SELECT b AS c").expressions[0].output_name
210            'c'
211            >>> parse_one("SELECT 1 + 2").expressions[0].output_name
212            ''
213        """
214        return ""
215
216    @property
217    def type(self) -> t.Optional[DataType]:
218        return self._type
219
220    @type.setter
221    def type(self, dtype: t.Optional[DataType | DataType.Type | str]) -> None:
222        if dtype and not isinstance(dtype, DataType):
223            dtype = DataType.build(dtype)
224        self._type = dtype  # type: ignore
225
226    @property
227    def meta(self) -> t.Dict[str, t.Any]:
228        if self._meta is None:
229            self._meta = {}
230        return self._meta
231
232    def __deepcopy__(self, memo):
233        copy = self.__class__(**deepcopy(self.args))
234        if self.comments is not None:
235            copy.comments = deepcopy(self.comments)
236
237        if self._type is not None:
238            copy._type = self._type.copy()
239
240        if self._meta is not None:
241            copy._meta = deepcopy(self._meta)
242
243        return copy
244
245    def copy(self):
246        """
247        Returns a deep copy of the expression.
248        """
249        new = deepcopy(self)
250        new.parent = self.parent
251        for item, parent, _ in new.bfs():
252            if isinstance(item, Expression) and parent:
253                item.parent = parent
254        return new
255
256    def append(self, arg_key, value):
257        """
258        Appends value to arg_key if it's a list or sets it as a new list.
259
260        Args:
261            arg_key (str): name of the list expression arg
262            value (Any): value to append to the list
263        """
264        if not isinstance(self.args.get(arg_key), list):
265            self.args[arg_key] = []
266        self.args[arg_key].append(value)
267        self._set_parent(arg_key, value)
268
269    def set(self, arg_key, value):
270        """
271        Sets `arg_key` to `value`.
272
273        Args:
274            arg_key (str): name of the expression arg.
275            value: value to set the arg to.
276        """
277        self.args[arg_key] = value
278        self._set_parent(arg_key, value)
279
280    def _set_parent(self, arg_key, value):
281        if isinstance(value, Expression):
282            value.parent = self
283            value.arg_key = arg_key
284        elif isinstance(value, list):
285            for v in value:
286                if isinstance(v, Expression):
287                    v.parent = self
288                    v.arg_key = arg_key
289
290    @property
291    def depth(self):
292        """
293        Returns the depth of this tree.
294        """
295        if self.parent:
296            return self.parent.depth + 1
297        return 0
298
299    def find(self, *expression_types: t.Type[E], bfs=True) -> E | None:
300        """
301        Returns the first node in this tree which matches at least one of
302        the specified types.
303
304        Args:
305            expression_types (type): the expression type(s) to match.
306
307        Returns:
308            The node which matches the criteria or None if no such node was found.
309        """
310        return next(self.find_all(*expression_types, bfs=bfs), None)
311
312    def find_all(self, *expression_types: t.Type[E], bfs=True) -> t.Iterator[E]:
313        """
314        Returns a generator object which visits all nodes in this tree and only
315        yields those that match at least one of the specified expression types.
316
317        Args:
318            expression_types (type): the expression type(s) to match.
319
320        Returns:
321            The generator object.
322        """
323        for expression, _, _ in self.walk(bfs=bfs):
324            if isinstance(expression, expression_types):
325                yield expression
326
327    def find_ancestor(self, *expression_types: t.Type[E]) -> E | None:
328        """
329        Returns a nearest parent matching expression_types.
330
331        Args:
332            expression_types (type): the expression type(s) to match.
333
334        Returns:
335            The parent node.
336        """
337        ancestor = self.parent
338        while ancestor and not isinstance(ancestor, expression_types):
339            ancestor = ancestor.parent
340        # ignore type because mypy doesn't know that we're checking type in the loop
341        return ancestor  # type: ignore[return-value]
342
343    @property
344    def parent_select(self):
345        """
346        Returns the parent select statement.
347        """
348        return self.find_ancestor(Select)
349
350    def root(self) -> Expression:
351        """
352        Returns the root expression of this tree.
353        """
354        expression = self
355        while expression.parent:
356            expression = expression.parent
357        return expression
358
359    def walk(self, bfs=True, prune=None):
360        """
361        Returns a generator object which visits all nodes in this tree.
362
363        Args:
364            bfs (bool): if set to True the BFS traversal order will be applied,
365                otherwise the DFS traversal will be used instead.
366            prune ((node, parent, arg_key) -> bool): callable that returns True if
367                the generator should stop traversing this branch of the tree.
368
369        Returns:
370            the generator object.
371        """
372        if bfs:
373            yield from self.bfs(prune=prune)
374        else:
375            yield from self.dfs(prune=prune)
376
377    def dfs(self, parent=None, key=None, prune=None):
378        """
379        Returns a generator object which visits all nodes in this tree in
380        the DFS (Depth-first) order.
381
382        Returns:
383            The generator object.
384        """
385        parent = parent or self.parent
386        yield self, parent, key
387        if prune and prune(self, parent, key):
388            return
389
390        for k, v in self.args.items():
391            for node in ensure_collection(v):
392                if isinstance(node, Expression):
393                    yield from node.dfs(self, k, prune)
394
395    def bfs(self, prune=None):
396        """
397        Returns a generator object which visits all nodes in this tree in
398        the BFS (Breadth-first) order.
399
400        Returns:
401            The generator object.
402        """
403        queue = deque([(self, self.parent, None)])
404
405        while queue:
406            item, parent, key = queue.popleft()
407
408            yield item, parent, key
409            if prune and prune(item, parent, key):
410                continue
411
412            if isinstance(item, Expression):
413                for k, v in item.args.items():
414                    for node in ensure_collection(v):
415                        if isinstance(node, Expression):
416                            queue.append((node, item, k))
417
418    def unnest(self):
419        """
420        Returns the first non parenthesis child or self.
421        """
422        expression = self
423        while isinstance(expression, Paren):
424            expression = expression.this
425        return expression
426
427    def unalias(self):
428        """
429        Returns the inner expression if this is an Alias.
430        """
431        if isinstance(self, Alias):
432            return self.this
433        return self
434
435    def unnest_operands(self):
436        """
437        Returns unnested operands as a tuple.
438        """
439        return tuple(arg.unnest() for arg in self.args.values() if arg)
440
441    def flatten(self, unnest=True):
442        """
443        Returns a generator which yields child nodes who's parents are the same class.
444
445        A AND B AND C -> [A, B, C]
446        """
447        for node, _, _ in self.dfs(prune=lambda n, p, *_: p and not isinstance(n, self.__class__)):
448            if not isinstance(node, self.__class__):
449                yield node.unnest() if unnest else node
450
451    def __str__(self):
452        return self.sql()
453
454    def __repr__(self):
455        return self._to_s()
456
457    def sql(self, dialect: DialectType = None, **opts) -> str:
458        """
459        Returns SQL string representation of this tree.
460
461        Args:
462            dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql").
463            opts: other `sqlglot.generator.Generator` options.
464
465        Returns:
466            The SQL string.
467        """
468        from sqlglot.dialects import Dialect
469
470        return Dialect.get_or_raise(dialect)().generate(self, **opts)
471
472    def _to_s(self, hide_missing: bool = True, level: int = 0) -> str:
473        indent = "" if not level else "\n"
474        indent += "".join(["  "] * level)
475        left = f"({self.key.upper()} "
476
477        args: t.Dict[str, t.Any] = {
478            k: ", ".join(
479                v._to_s(hide_missing=hide_missing, level=level + 1)
480                if hasattr(v, "_to_s")
481                else str(v)
482                for v in ensure_collection(vs)
483                if v is not None
484            )
485            for k, vs in self.args.items()
486        }
487        args["comments"] = self.comments
488        args["type"] = self.type
489        args = {k: v for k, v in args.items() if v or not hide_missing}
490
491        right = ", ".join(f"{k}: {v}" for k, v in args.items())
492        right += ")"
493
494        return indent + left + right
495
496    def transform(self, fun, *args, copy=True, **kwargs):
497        """
498        Recursively visits all tree nodes (excluding already transformed ones)
499        and applies the given transformation function to each node.
500
501        Args:
502            fun (function): a function which takes a node as an argument and returns a
503                new transformed node or the same node without modifications. If the function
504                returns None, then the corresponding node will be removed from the syntax tree.
505            copy (bool): if set to True a new tree instance is constructed, otherwise the tree is
506                modified in place.
507
508        Returns:
509            The transformed tree.
510        """
511        node = self.copy() if copy else self
512        new_node = fun(node, *args, **kwargs)
513
514        if new_node is None or not isinstance(new_node, Expression):
515            return new_node
516        if new_node is not node:
517            new_node.parent = node.parent
518            return new_node
519
520        replace_children(new_node, lambda child: child.transform(fun, *args, copy=False, **kwargs))
521        return new_node
522
523    def replace(self, expression):
524        """
525        Swap out this expression with a new expression.
526
527        For example::
528
529            >>> tree = Select().select("x").from_("tbl")
530            >>> tree.find(Column).replace(Column(this="y"))
531            (COLUMN this: y)
532            >>> tree.sql()
533            'SELECT y FROM tbl'
534
535        Args:
536            expression (Expression|None): new node
537
538        Returns:
539            The new expression or expressions.
540        """
541        if not self.parent:
542            return expression
543
544        parent = self.parent
545        self.parent = None
546
547        replace_children(parent, lambda child: expression if child is self else child)
548        return expression
549
550    def pop(self):
551        """
552        Remove this expression from its AST.
553        """
554        self.replace(None)
555
556    def assert_is(self, type_):
557        """
558        Assert that this `Expression` is an instance of `type_`.
559
560        If it is NOT an instance of `type_`, this raises an assertion error.
561        Otherwise, this returns this expression.
562
563        Examples:
564            This is useful for type security in chained expressions:
565
566            >>> import sqlglot
567            >>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql()
568            'SELECT x, z FROM y'
569        """
570        assert isinstance(self, type_)
571        return self
572
573    def error_messages(self, args: t.Optional[t.Sequence] = None) -> t.List[str]:
574        """
575        Checks if this expression is valid (e.g. all mandatory args are set).
576
577        Args:
578            args: a sequence of values that were used to instantiate a Func expression. This is used
579                to check that the provided arguments don't exceed the function argument limit.
580
581        Returns:
582            A list of error messages for all possible errors that were found.
583        """
584        errors: t.List[str] = []
585
586        for k in self.args:
587            if k not in self.arg_types:
588                errors.append(f"Unexpected keyword: '{k}' for {self.__class__}")
589        for k, mandatory in self.arg_types.items():
590            v = self.args.get(k)
591            if mandatory and (v is None or (isinstance(v, list) and not v)):
592                errors.append(f"Required keyword: '{k}' missing for {self.__class__}")
593
594        if (
595            args
596            and isinstance(self, Func)
597            and len(args) > len(self.arg_types)
598            and not self.is_var_len_args
599        ):
600            errors.append(
601                f"The number of provided arguments ({len(args)}) is greater than "
602                f"the maximum number of supported arguments ({len(self.arg_types)})"
603            )
604
605        return errors
606
607    def dump(self):
608        """
609        Dump this Expression to a JSON-serializable dict.
610        """
611        from sqlglot.serde import dump
612
613        return dump(self)
614
615    @classmethod
616    def load(cls, obj):
617        """
618        Load a dict (as returned by `Expression.dump`) into an Expression instance.
619        """
620        from sqlglot.serde import load
621
622        return load(obj)

The base class for all expressions in a syntax tree. Each Expression encapsulates any necessary context, such as its child expressions, their names (arg keys), and whether a given child expression is optional or not.

Attributes:
  • key: a unique key for each class in the Expression hierarchy. This is useful for hashing and representing expressions as strings.
  • arg_types: determines what arguments (child nodes) are supported by an expression. It maps arg keys to booleans that indicate whether the corresponding args are optional.
Example:
>>> class Foo(Expression):
...     arg_types = {"this": True, "expression": False}

The above definition informs us that Foo is an Expression that requires an argument called "this" and may also optionally receive an argument called "expression".

Arguments:
  • args: a mapping used for retrieving the arguments of an expression, given their arg keys.
  • parent: a reference to the parent expression (or None, in case of root expressions).
  • arg_key: the arg key an expression is associated with, i.e. the name its parent expression uses to refer to it.
  • comments: a list of comments that are associated with a given expression. This is used in order to preserve comments when transpiling SQL code.
  • _type: the sqlglot.expressions.DataType type of an expression. This is inferred by the optimizer, in order to enable some transformations that require type information.
Expression(**args: Any)
90    def __init__(self, **args: t.Any):
91        self.args: t.Dict[str, t.Any] = args
92        self.parent: t.Optional[Expression] = None
93        self.arg_key: t.Optional[str] = None
94        self.comments: t.Optional[t.List[str]] = None
95        self._type: t.Optional[DataType] = None
96        self._meta: t.Optional[t.Dict[str, t.Any]] = None
97
98        for arg_key, value in self.args.items():
99            self._set_parent(arg_key, value)
this

Retrieves the argument with key "this".

expression

Retrieves the argument with key "expression".

expressions

Retrieves the argument with key "expressions".

def text(self, key) -> str:
135    def text(self, key) -> str:
136        """
137        Returns a textual representation of the argument corresponding to "key". This can only be used
138        for args that are strings or leaf Expression instances, such as identifiers and literals.
139        """
140        field = self.args.get(key)
141        if isinstance(field, str):
142            return field
143        if isinstance(field, (Identifier, Literal, Var)):
144            return field.this
145        if isinstance(field, (Star, Null)):
146            return field.name
147        return ""

Returns a textual representation of the argument corresponding to "key". This can only be used for args that are strings or leaf Expression instances, such as identifiers and literals.

is_string: bool

Checks whether a Literal expression is a string.

is_number: bool

Checks whether a Literal expression is a number.

is_int: bool

Checks whether a Literal expression is an integer.

is_star: bool

Checks whether an expression is a star.

alias: str

Returns the alias of the expression, or an empty string if it's not aliased.

output_name

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
def copy(self):
245    def copy(self):
246        """
247        Returns a deep copy of the expression.
248        """
249        new = deepcopy(self)
250        new.parent = self.parent
251        for item, parent, _ in new.bfs():
252            if isinstance(item, Expression) and parent:
253                item.parent = parent
254        return new

Returns a deep copy of the expression.

def append(self, arg_key, value):
256    def append(self, arg_key, value):
257        """
258        Appends value to arg_key if it's a list or sets it as a new list.
259
260        Args:
261            arg_key (str): name of the list expression arg
262            value (Any): value to append to the list
263        """
264        if not isinstance(self.args.get(arg_key), list):
265            self.args[arg_key] = []
266        self.args[arg_key].append(value)
267        self._set_parent(arg_key, value)

Appends value to arg_key if it's a list or sets it as a new list.

Arguments:
  • arg_key (str): name of the list expression arg
  • value (Any): value to append to the list
def set(self, arg_key, value):
269    def set(self, arg_key, value):
270        """
271        Sets `arg_key` to `value`.
272
273        Args:
274            arg_key (str): name of the expression arg.
275            value: value to set the arg to.
276        """
277        self.args[arg_key] = value
278        self._set_parent(arg_key, value)

Sets arg_key to value.

Arguments:
  • arg_key (str): name of the expression arg.
  • value: value to set the arg to.
depth

Returns the depth of this tree.

def find(self, *expression_types: Type[~E], bfs=True) -> Optional[~E]:
299    def find(self, *expression_types: t.Type[E], bfs=True) -> E | None:
300        """
301        Returns the first node in this tree which matches at least one of
302        the specified types.
303
304        Args:
305            expression_types (type): the expression type(s) to match.
306
307        Returns:
308            The node which matches the criteria or None if no such node was found.
309        """
310        return next(self.find_all(*expression_types, bfs=bfs), None)

Returns the first node in this tree which matches at least one of the specified types.

Arguments:
  • expression_types (type): the expression type(s) to match.
Returns:

The node which matches the criteria or None if no such node was found.

def find_all(self, *expression_types: Type[~E], bfs=True) -> Iterator[~E]:
312    def find_all(self, *expression_types: t.Type[E], bfs=True) -> t.Iterator[E]:
313        """
314        Returns a generator object which visits all nodes in this tree and only
315        yields those that match at least one of the specified expression types.
316
317        Args:
318            expression_types (type): the expression type(s) to match.
319
320        Returns:
321            The generator object.
322        """
323        for expression, _, _ in self.walk(bfs=bfs):
324            if isinstance(expression, expression_types):
325                yield expression

Returns a generator object which visits all nodes in this tree and only yields those that match at least one of the specified expression types.

Arguments:
  • expression_types (type): the expression type(s) to match.
Returns:

The generator object.

def find_ancestor(self, *expression_types: Type[~E]) -> Optional[~E]:
327    def find_ancestor(self, *expression_types: t.Type[E]) -> E | None:
328        """
329        Returns a nearest parent matching expression_types.
330
331        Args:
332            expression_types (type): the expression type(s) to match.
333
334        Returns:
335            The parent node.
336        """
337        ancestor = self.parent
338        while ancestor and not isinstance(ancestor, expression_types):
339            ancestor = ancestor.parent
340        # ignore type because mypy doesn't know that we're checking type in the loop
341        return ancestor  # type: ignore[return-value]

Returns a nearest parent matching expression_types.

Arguments:
  • expression_types (type): the expression type(s) to match.
Returns:

The parent node.

parent_select

Returns the parent select statement.

def root(self) -> sqlglot.expressions.Expression:
350    def root(self) -> Expression:
351        """
352        Returns the root expression of this tree.
353        """
354        expression = self
355        while expression.parent:
356            expression = expression.parent
357        return expression

Returns the root expression of this tree.

def walk(self, bfs=True, prune=None):
359    def walk(self, bfs=True, prune=None):
360        """
361        Returns a generator object which visits all nodes in this tree.
362
363        Args:
364            bfs (bool): if set to True the BFS traversal order will be applied,
365                otherwise the DFS traversal will be used instead.
366            prune ((node, parent, arg_key) -> bool): callable that returns True if
367                the generator should stop traversing this branch of the tree.
368
369        Returns:
370            the generator object.
371        """
372        if bfs:
373            yield from self.bfs(prune=prune)
374        else:
375            yield from self.dfs(prune=prune)

Returns a generator object which visits all nodes in this tree.

Arguments:
  • bfs (bool): if set to True the BFS traversal order will be applied, otherwise the DFS traversal will be used instead.
  • prune ((node, parent, arg_key) -> bool): callable that returns True if the generator should stop traversing this branch of the tree.
Returns:

the generator object.

def dfs(self, parent=None, key=None, prune=None):
377    def dfs(self, parent=None, key=None, prune=None):
378        """
379        Returns a generator object which visits all nodes in this tree in
380        the DFS (Depth-first) order.
381
382        Returns:
383            The generator object.
384        """
385        parent = parent or self.parent
386        yield self, parent, key
387        if prune and prune(self, parent, key):
388            return
389
390        for k, v in self.args.items():
391            for node in ensure_collection(v):
392                if isinstance(node, Expression):
393                    yield from node.dfs(self, k, prune)

Returns a generator object which visits all nodes in this tree in the DFS (Depth-first) order.

Returns:

The generator object.

def bfs(self, prune=None):
395    def bfs(self, prune=None):
396        """
397        Returns a generator object which visits all nodes in this tree in
398        the BFS (Breadth-first) order.
399
400        Returns:
401            The generator object.
402        """
403        queue = deque([(self, self.parent, None)])
404
405        while queue:
406            item, parent, key = queue.popleft()
407
408            yield item, parent, key
409            if prune and prune(item, parent, key):
410                continue
411
412            if isinstance(item, Expression):
413                for k, v in item.args.items():
414                    for node in ensure_collection(v):
415                        if isinstance(node, Expression):
416                            queue.append((node, item, k))

Returns a generator object which visits all nodes in this tree in the BFS (Breadth-first) order.

Returns:

The generator object.

def unnest(self):
418    def unnest(self):
419        """
420        Returns the first non parenthesis child or self.
421        """
422        expression = self
423        while isinstance(expression, Paren):
424            expression = expression.this
425        return expression

Returns the first non parenthesis child or self.

def unalias(self):
427    def unalias(self):
428        """
429        Returns the inner expression if this is an Alias.
430        """
431        if isinstance(self, Alias):
432            return self.this
433        return self

Returns the inner expression if this is an Alias.

def unnest_operands(self):
435    def unnest_operands(self):
436        """
437        Returns unnested operands as a tuple.
438        """
439        return tuple(arg.unnest() for arg in self.args.values() if arg)

Returns unnested operands as a tuple.

def flatten(self, unnest=True):
441    def flatten(self, unnest=True):
442        """
443        Returns a generator which yields child nodes who's parents are the same class.
444
445        A AND B AND C -> [A, B, C]
446        """
447        for node, _, _ in self.dfs(prune=lambda n, p, *_: p and not isinstance(n, self.__class__)):
448            if not isinstance(node, self.__class__):
449                yield node.unnest() if unnest else node

Returns a generator which yields child nodes who's parents are the same class.

A AND B AND C -> [A, B, C]

def sql( self, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts) -> str:
457    def sql(self, dialect: DialectType = None, **opts) -> str:
458        """
459        Returns SQL string representation of this tree.
460
461        Args:
462            dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql").
463            opts: other `sqlglot.generator.Generator` options.
464
465        Returns:
466            The SQL string.
467        """
468        from sqlglot.dialects import Dialect
469
470        return Dialect.get_or_raise(dialect)().generate(self, **opts)

Returns SQL string representation of this tree.

Arguments:
  • dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql").
  • opts: other sqlglot.generator.Generator options.
Returns:

The SQL string.

def transform(self, fun, *args, copy=True, **kwargs):
496    def transform(self, fun, *args, copy=True, **kwargs):
497        """
498        Recursively visits all tree nodes (excluding already transformed ones)
499        and applies the given transformation function to each node.
500
501        Args:
502            fun (function): a function which takes a node as an argument and returns a
503                new transformed node or the same node without modifications. If the function
504                returns None, then the corresponding node will be removed from the syntax tree.
505            copy (bool): if set to True a new tree instance is constructed, otherwise the tree is
506                modified in place.
507
508        Returns:
509            The transformed tree.
510        """
511        node = self.copy() if copy else self
512        new_node = fun(node, *args, **kwargs)
513
514        if new_node is None or not isinstance(new_node, Expression):
515            return new_node
516        if new_node is not node:
517            new_node.parent = node.parent
518            return new_node
519
520        replace_children(new_node, lambda child: child.transform(fun, *args, copy=False, **kwargs))
521        return new_node

Recursively visits all tree nodes (excluding already transformed ones) and applies the given transformation function to each node.

Arguments:
  • fun (function): a function which takes a node as an argument and returns a new transformed node or the same node without modifications. If the function returns None, then the corresponding node will be removed from the syntax tree.
  • copy (bool): if set to True a new tree instance is constructed, otherwise the tree is modified in place.
Returns:

The transformed tree.

def replace(self, expression):
523    def replace(self, expression):
524        """
525        Swap out this expression with a new expression.
526
527        For example::
528
529            >>> tree = Select().select("x").from_("tbl")
530            >>> tree.find(Column).replace(Column(this="y"))
531            (COLUMN this: y)
532            >>> tree.sql()
533            'SELECT y FROM tbl'
534
535        Args:
536            expression (Expression|None): new node
537
538        Returns:
539            The new expression or expressions.
540        """
541        if not self.parent:
542            return expression
543
544        parent = self.parent
545        self.parent = None
546
547        replace_children(parent, lambda child: expression if child is self else child)
548        return expression

Swap out this expression with a new expression.

For example::

>>> tree = Select().select("x").from_("tbl")
>>> tree.find(Column).replace(Column(this="y"))
(COLUMN this: y)
>>> tree.sql()
'SELECT y FROM tbl'
Arguments:
  • expression (Expression|None): new node
Returns:

The new expression or expressions.

def pop(self):
550    def pop(self):
551        """
552        Remove this expression from its AST.
553        """
554        self.replace(None)

Remove this expression from its AST.

def assert_is(self, type_):
556    def assert_is(self, type_):
557        """
558        Assert that this `Expression` is an instance of `type_`.
559
560        If it is NOT an instance of `type_`, this raises an assertion error.
561        Otherwise, this returns this expression.
562
563        Examples:
564            This is useful for type security in chained expressions:
565
566            >>> import sqlglot
567            >>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql()
568            'SELECT x, z FROM y'
569        """
570        assert isinstance(self, type_)
571        return self

Assert that this Expression is an instance of type_.

If it is NOT an instance of type_, this raises an assertion error. Otherwise, this returns this expression.

Examples:

This is useful for type security in chained expressions:

>>> import sqlglot
>>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql()
'SELECT x, z FROM y'
def error_messages(self, args: Optional[Sequence] = None) -> List[str]:
573    def error_messages(self, args: t.Optional[t.Sequence] = None) -> t.List[str]:
574        """
575        Checks if this expression is valid (e.g. all mandatory args are set).
576
577        Args:
578            args: a sequence of values that were used to instantiate a Func expression. This is used
579                to check that the provided arguments don't exceed the function argument limit.
580
581        Returns:
582            A list of error messages for all possible errors that were found.
583        """
584        errors: t.List[str] = []
585
586        for k in self.args:
587            if k not in self.arg_types:
588                errors.append(f"Unexpected keyword: '{k}' for {self.__class__}")
589        for k, mandatory in self.arg_types.items():
590            v = self.args.get(k)
591            if mandatory and (v is None or (isinstance(v, list) and not v)):
592                errors.append(f"Required keyword: '{k}' missing for {self.__class__}")
593
594        if (
595            args
596            and isinstance(self, Func)
597            and len(args) > len(self.arg_types)
598            and not self.is_var_len_args
599        ):
600            errors.append(
601                f"The number of provided arguments ({len(args)}) is greater than "
602                f"the maximum number of supported arguments ({len(self.arg_types)})"
603            )
604
605        return errors

Checks if this expression is valid (e.g. all mandatory args are set).

Arguments:
  • args: a sequence of values that were used to instantiate a Func expression. This is used to check that the provided arguments don't exceed the function argument limit.
Returns:

A list of error messages for all possible errors that were found.

def dump(self):
607    def dump(self):
608        """
609        Dump this Expression to a JSON-serializable dict.
610        """
611        from sqlglot.serde import dump
612
613        return dump(self)

Dump this Expression to a JSON-serializable dict.

@classmethod
def load(cls, obj):
615    @classmethod
616    def load(cls, obj):
617        """
618        Load a dict (as returned by `Expression.dump`) into an Expression instance.
619        """
620        from sqlglot.serde import load
621
622        return load(obj)

Load a dict (as returned by Expression.dump) into an Expression instance.

class Condition(Expression):
632class Condition(Expression):
633    def and_(self, *expressions, dialect=None, **opts):
634        """
635        AND this condition with one or multiple expressions.
636
637        Example:
638            >>> condition("x=1").and_("y=1").sql()
639            'x = 1 AND y = 1'
640
641        Args:
642            *expressions (str | Expression): the SQL code strings to parse.
643                If an `Expression` instance is passed, it will be used as-is.
644            dialect (str): the dialect used to parse the input expression.
645            opts (kwargs): other options to use to parse the input expressions.
646
647        Returns:
648            And: the new condition.
649        """
650        return and_(self, *expressions, dialect=dialect, **opts)
651
652    def or_(self, *expressions, dialect=None, **opts):
653        """
654        OR this condition with one or multiple expressions.
655
656        Example:
657            >>> condition("x=1").or_("y=1").sql()
658            'x = 1 OR y = 1'
659
660        Args:
661            *expressions (str | Expression): the SQL code strings to parse.
662                If an `Expression` instance is passed, it will be used as-is.
663            dialect (str): the dialect used to parse the input expression.
664            opts (kwargs): other options to use to parse the input expressions.
665
666        Returns:
667            Or: the new condition.
668        """
669        return or_(self, *expressions, dialect=dialect, **opts)
670
671    def not_(self):
672        """
673        Wrap this condition with NOT.
674
675        Example:
676            >>> condition("x=1").not_().sql()
677            'NOT x = 1'
678
679        Returns:
680            Not: the new condition.
681        """
682        return not_(self)
def and_(self, *expressions, dialect=None, **opts):
633    def and_(self, *expressions, dialect=None, **opts):
634        """
635        AND this condition with one or multiple expressions.
636
637        Example:
638            >>> condition("x=1").and_("y=1").sql()
639            'x = 1 AND y = 1'
640
641        Args:
642            *expressions (str | Expression): the SQL code strings to parse.
643                If an `Expression` instance is passed, it will be used as-is.
644            dialect (str): the dialect used to parse the input expression.
645            opts (kwargs): other options to use to parse the input expressions.
646
647        Returns:
648            And: the new condition.
649        """
650        return and_(self, *expressions, dialect=dialect, **opts)

AND this condition with one or multiple expressions.

Example:
>>> condition("x=1").and_("y=1").sql()
'x = 1 AND y = 1'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

And: the new condition.

def or_(self, *expressions, dialect=None, **opts):
652    def or_(self, *expressions, dialect=None, **opts):
653        """
654        OR this condition with one or multiple expressions.
655
656        Example:
657            >>> condition("x=1").or_("y=1").sql()
658            'x = 1 OR y = 1'
659
660        Args:
661            *expressions (str | Expression): the SQL code strings to parse.
662                If an `Expression` instance is passed, it will be used as-is.
663            dialect (str): the dialect used to parse the input expression.
664            opts (kwargs): other options to use to parse the input expressions.
665
666        Returns:
667            Or: the new condition.
668        """
669        return or_(self, *expressions, dialect=dialect, **opts)

OR this condition with one or multiple expressions.

Example:
>>> condition("x=1").or_("y=1").sql()
'x = 1 OR y = 1'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Or: the new condition.

def not_(self):
671    def not_(self):
672        """
673        Wrap this condition with NOT.
674
675        Example:
676            >>> condition("x=1").not_().sql()
677            'NOT x = 1'
678
679        Returns:
680            Not: the new condition.
681        """
682        return not_(self)

Wrap this condition with NOT.

Example:
>>> condition("x=1").not_().sql()
'NOT x = 1'
Returns:

Not: the new condition.

class Predicate(Condition):
685class Predicate(Condition):
686    """Relationships like x = y, x > 1, x >= y."""

Relationships like x = y, x > 1, x >= y.

class DerivedTable(Expression):
689class DerivedTable(Expression):
690    @property
691    def alias_column_names(self):
692        table_alias = self.args.get("alias")
693        if not table_alias:
694            return []
695        column_list = table_alias.assert_is(TableAlias).args.get("columns") or []
696        return [c.name for c in column_list]
697
698    @property
699    def selects(self):
700        alias = self.args.get("alias")
701
702        if alias:
703            return alias.columns
704        return []
705
706    @property
707    def named_selects(self):
708        return [select.output_name for select in self.selects]
class Unionable(Expression):
711class Unionable(Expression):
712    def union(self, expression, distinct=True, dialect=None, **opts):
713        """
714        Builds a UNION expression.
715
716        Example:
717            >>> import sqlglot
718            >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql()
719            'SELECT * FROM foo UNION SELECT * FROM bla'
720
721        Args:
722            expression (str | Expression): the SQL code string.
723                If an `Expression` instance is passed, it will be used as-is.
724            distinct (bool): set the DISTINCT flag if and only if this is true.
725            dialect (str): the dialect used to parse the input expression.
726            opts (kwargs): other options to use to parse the input expressions.
727        Returns:
728            Union: the Union expression.
729        """
730        return union(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
731
732    def intersect(self, expression, distinct=True, dialect=None, **opts):
733        """
734        Builds an INTERSECT expression.
735
736        Example:
737            >>> import sqlglot
738            >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql()
739            'SELECT * FROM foo INTERSECT SELECT * FROM bla'
740
741        Args:
742            expression (str | Expression): the SQL code string.
743                If an `Expression` instance is passed, it will be used as-is.
744            distinct (bool): set the DISTINCT flag if and only if this is true.
745            dialect (str): the dialect used to parse the input expression.
746            opts (kwargs): other options to use to parse the input expressions.
747        Returns:
748            Intersect: the Intersect expression
749        """
750        return intersect(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
751
752    def except_(self, expression, distinct=True, dialect=None, **opts):
753        """
754        Builds an EXCEPT expression.
755
756        Example:
757            >>> import sqlglot
758            >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql()
759            'SELECT * FROM foo EXCEPT SELECT * FROM bla'
760
761        Args:
762            expression (str | Expression): the SQL code string.
763                If an `Expression` instance is passed, it will be used as-is.
764            distinct (bool): set the DISTINCT flag if and only if this is true.
765            dialect (str): the dialect used to parse the input expression.
766            opts (kwargs): other options to use to parse the input expressions.
767        Returns:
768            Except: the Except expression
769        """
770        return except_(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
def union(self, expression, distinct=True, dialect=None, **opts):
712    def union(self, expression, distinct=True, dialect=None, **opts):
713        """
714        Builds a UNION expression.
715
716        Example:
717            >>> import sqlglot
718            >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql()
719            'SELECT * FROM foo UNION SELECT * FROM bla'
720
721        Args:
722            expression (str | Expression): the SQL code string.
723                If an `Expression` instance is passed, it will be used as-is.
724            distinct (bool): set the DISTINCT flag if and only if this is true.
725            dialect (str): the dialect used to parse the input expression.
726            opts (kwargs): other options to use to parse the input expressions.
727        Returns:
728            Union: the Union expression.
729        """
730        return union(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)

Builds a UNION expression.

Example:
>>> import sqlglot
>>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql()
'SELECT * FROM foo UNION SELECT * FROM bla'
Arguments:
  • expression (str | Expression): the SQL code string. If an Expression instance is passed, it will be used as-is.
  • distinct (bool): set the DISTINCT flag if and only if this is true.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Union: the Union expression.

def intersect(self, expression, distinct=True, dialect=None, **opts):
732    def intersect(self, expression, distinct=True, dialect=None, **opts):
733        """
734        Builds an INTERSECT expression.
735
736        Example:
737            >>> import sqlglot
738            >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql()
739            'SELECT * FROM foo INTERSECT SELECT * FROM bla'
740
741        Args:
742            expression (str | Expression): the SQL code string.
743                If an `Expression` instance is passed, it will be used as-is.
744            distinct (bool): set the DISTINCT flag if and only if this is true.
745            dialect (str): the dialect used to parse the input expression.
746            opts (kwargs): other options to use to parse the input expressions.
747        Returns:
748            Intersect: the Intersect expression
749        """
750        return intersect(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)

Builds an INTERSECT expression.

Example:
>>> import sqlglot
>>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql()
'SELECT * FROM foo INTERSECT SELECT * FROM bla'
Arguments:
  • expression (str | Expression): the SQL code string. If an Expression instance is passed, it will be used as-is.
  • distinct (bool): set the DISTINCT flag if and only if this is true.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Intersect: the Intersect expression

def except_(self, expression, distinct=True, dialect=None, **opts):
752    def except_(self, expression, distinct=True, dialect=None, **opts):
753        """
754        Builds an EXCEPT expression.
755
756        Example:
757            >>> import sqlglot
758            >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql()
759            'SELECT * FROM foo EXCEPT SELECT * FROM bla'
760
761        Args:
762            expression (str | Expression): the SQL code string.
763                If an `Expression` instance is passed, it will be used as-is.
764            distinct (bool): set the DISTINCT flag if and only if this is true.
765            dialect (str): the dialect used to parse the input expression.
766            opts (kwargs): other options to use to parse the input expressions.
767        Returns:
768            Except: the Except expression
769        """
770        return except_(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)

Builds an EXCEPT expression.

Example:
>>> import sqlglot
>>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql()
'SELECT * FROM foo EXCEPT SELECT * FROM bla'
Arguments:
  • expression (str | Expression): the SQL code string. If an Expression instance is passed, it will be used as-is.
  • distinct (bool): set the DISTINCT flag if and only if this is true.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Except: the Except expression

class UDTF(DerivedTable, Unionable):
773class UDTF(DerivedTable, Unionable):
774    pass
class Cache(Expression):
777class Cache(Expression):
778    arg_types = {
779        "with": False,
780        "this": True,
781        "lazy": False,
782        "options": False,
783        "expression": False,
784    }
class Uncache(Expression):
787class Uncache(Expression):
788    arg_types = {"this": True, "exists": False}
class Create(Expression):
791class Create(Expression):
792    arg_types = {
793        "with": False,
794        "this": True,
795        "kind": True,
796        "expression": False,
797        "exists": False,
798        "properties": False,
799        "replace": False,
800        "unique": False,
801        "volatile": False,
802        "indexes": False,
803        "no_schema_binding": False,
804        "begin": False,
805    }
class Describe(Expression):
808class Describe(Expression):
809    arg_types = {"this": True, "kind": False}
class Set(Expression):
812class Set(Expression):
813    arg_types = {"expressions": True}
class SetItem(Expression):
816class SetItem(Expression):
817    arg_types = {
818        "this": False,
819        "expressions": False,
820        "kind": False,
821        "collate": False,  # MySQL SET NAMES statement
822        "global": False,
823    }
class Show(Expression):
826class Show(Expression):
827    arg_types = {
828        "this": True,
829        "target": False,
830        "offset": False,
831        "limit": False,
832        "like": False,
833        "where": False,
834        "db": False,
835        "full": False,
836        "mutex": False,
837        "query": False,
838        "channel": False,
839        "global": False,
840        "log": False,
841        "position": False,
842        "types": False,
843    }
class UserDefinedFunction(Expression):
846class UserDefinedFunction(Expression):
847    arg_types = {"this": True, "expressions": False, "wrapped": False}
class CharacterSet(Expression):
850class CharacterSet(Expression):
851    arg_types = {"this": True, "default": False}
class With(Expression):
854class With(Expression):
855    arg_types = {"expressions": True, "recursive": False}
856
857    @property
858    def recursive(self) -> bool:
859        return bool(self.args.get("recursive"))
class WithinGroup(Expression):
862class WithinGroup(Expression):
863    arg_types = {"this": True, "expression": False}
class CTE(DerivedTable):
866class CTE(DerivedTable):
867    arg_types = {"this": True, "alias": True}
class TableAlias(Expression):
870class TableAlias(Expression):
871    arg_types = {"this": False, "columns": False}
872
873    @property
874    def columns(self):
875        return self.args.get("columns") or []
class BitString(Condition):
878class BitString(Condition):
879    pass
class HexString(Condition):
882class HexString(Condition):
883    pass
class ByteString(Condition):
886class ByteString(Condition):
887    pass
class Column(Condition):
890class Column(Condition):
891    arg_types = {"this": True, "table": False, "db": False, "catalog": False, "join_mark": False}
892
893    @property
894    def table(self) -> str:
895        return self.text("table")
896
897    @property
898    def db(self) -> str:
899        return self.text("db")
900
901    @property
902    def catalog(self) -> str:
903        return self.text("catalog")
904
905    @property
906    def output_name(self) -> str:
907        return self.name
output_name: str

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
class ColumnDef(Expression):
910class ColumnDef(Expression):
911    arg_types = {
912        "this": True,
913        "kind": False,
914        "constraints": False,
915        "exists": False,
916    }
class AlterColumn(Expression):
919class AlterColumn(Expression):
920    arg_types = {
921        "this": True,
922        "dtype": False,
923        "collate": False,
924        "using": False,
925        "default": False,
926        "drop": False,
927    }
class RenameTable(Expression):
930class RenameTable(Expression):
931    pass
class SetTag(Expression):
934class SetTag(Expression):
935    arg_types = {"expressions": True, "unset": False}
class ColumnConstraint(Expression):
938class ColumnConstraint(Expression):
939    arg_types = {"this": False, "kind": True}
class ColumnConstraintKind(Expression):
942class ColumnConstraintKind(Expression):
943    pass
class AutoIncrementColumnConstraint(ColumnConstraintKind):
946class AutoIncrementColumnConstraint(ColumnConstraintKind):
947    pass
class CaseSpecificColumnConstraint(ColumnConstraintKind):
950class CaseSpecificColumnConstraint(ColumnConstraintKind):
951    arg_types = {"not_": True}
class CharacterSetColumnConstraint(ColumnConstraintKind):
954class CharacterSetColumnConstraint(ColumnConstraintKind):
955    arg_types = {"this": True}
class CheckColumnConstraint(ColumnConstraintKind):
958class CheckColumnConstraint(ColumnConstraintKind):
959    pass
class CollateColumnConstraint(ColumnConstraintKind):
962class CollateColumnConstraint(ColumnConstraintKind):
963    pass
class CommentColumnConstraint(ColumnConstraintKind):
966class CommentColumnConstraint(ColumnConstraintKind):
967    pass
class CompressColumnConstraint(ColumnConstraintKind):
970class CompressColumnConstraint(ColumnConstraintKind):
971    pass
class DateFormatColumnConstraint(ColumnConstraintKind):
974class DateFormatColumnConstraint(ColumnConstraintKind):
975    arg_types = {"this": True}
class DefaultColumnConstraint(ColumnConstraintKind):
978class DefaultColumnConstraint(ColumnConstraintKind):
979    pass
class EncodeColumnConstraint(ColumnConstraintKind):
982class EncodeColumnConstraint(ColumnConstraintKind):
983    pass
class GeneratedAsIdentityColumnConstraint(ColumnConstraintKind):
986class GeneratedAsIdentityColumnConstraint(ColumnConstraintKind):
987    # this: True -> ALWAYS, this: False -> BY DEFAULT
988    arg_types = {
989        "this": False,
990        "start": False,
991        "increment": False,
992        "minvalue": False,
993        "maxvalue": False,
994        "cycle": False,
995    }
class InlineLengthColumnConstraint(ColumnConstraintKind):
998class InlineLengthColumnConstraint(ColumnConstraintKind):
999    pass
class NotNullColumnConstraint(ColumnConstraintKind):
1002class NotNullColumnConstraint(ColumnConstraintKind):
1003    arg_types = {"allow_null": False}
class PrimaryKeyColumnConstraint(ColumnConstraintKind):
1006class PrimaryKeyColumnConstraint(ColumnConstraintKind):
1007    arg_types = {"desc": False}
class TitleColumnConstraint(ColumnConstraintKind):
1010class TitleColumnConstraint(ColumnConstraintKind):
1011    pass
class UniqueColumnConstraint(ColumnConstraintKind):
1014class UniqueColumnConstraint(ColumnConstraintKind):
1015    arg_types: t.Dict[str, t.Any] = {}
class UppercaseColumnConstraint(ColumnConstraintKind):
1018class UppercaseColumnConstraint(ColumnConstraintKind):
1019    arg_types: t.Dict[str, t.Any] = {}
class PathColumnConstraint(ColumnConstraintKind):
1022class PathColumnConstraint(ColumnConstraintKind):
1023    pass
class Constraint(Expression):
1026class Constraint(Expression):
1027    arg_types = {"this": True, "expressions": True}
class Delete(Expression):
1030class Delete(Expression):
1031    arg_types = {"with": False, "this": False, "using": False, "where": False}
class Drop(Expression):
1034class Drop(Expression):
1035    arg_types = {
1036        "this": False,
1037        "kind": False,
1038        "exists": False,
1039        "temporary": False,
1040        "materialized": False,
1041        "cascade": False,
1042    }
class Filter(Expression):
1045class Filter(Expression):
1046    arg_types = {"this": True, "expression": True}
class Check(Expression):
1049class Check(Expression):
1050    pass
class Directory(Expression):
1053class Directory(Expression):
1054    # https://spark.apache.org/docs/3.0.0-preview/sql-ref-syntax-dml-insert-overwrite-directory-hive.html
1055    arg_types = {"this": True, "local": False, "row_format": False}
class ForeignKey(Expression):
1058class ForeignKey(Expression):
1059    arg_types = {
1060        "expressions": True,
1061        "reference": False,
1062        "delete": False,
1063        "update": False,
1064    }
class PrimaryKey(Expression):
1067class PrimaryKey(Expression):
1068    arg_types = {"expressions": True, "options": False}
class Unique(Expression):
1071class Unique(Expression):
1072    arg_types = {"expressions": True}
class Into(Expression):
1077class Into(Expression):
1078    arg_types = {"this": True, "temporary": False, "unlogged": False}
class From(Expression):
1081class From(Expression):
1082    arg_types = {"expressions": True}
class Having(Expression):
1085class Having(Expression):
1086    pass
class Hint(Expression):
1089class Hint(Expression):
1090    arg_types = {"expressions": True}
class JoinHint(Expression):
1093class JoinHint(Expression):
1094    arg_types = {"this": True, "expressions": True}
class Identifier(Expression):
1097class Identifier(Expression):
1098    arg_types = {"this": True, "quoted": False}
1099
1100    @property
1101    def quoted(self):
1102        return bool(self.args.get("quoted"))
1103
1104    def __eq__(self, other):
1105        return isinstance(other, self.__class__) and _norm_arg(self.this) == _norm_arg(other.this)
1106
1107    def __hash__(self):
1108        return hash((self.key, self.this.lower()))
1109
1110    @property
1111    def output_name(self):
1112        return self.name
output_name

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
class Index(Expression):
1115class Index(Expression):
1116    arg_types = {
1117        "this": False,
1118        "table": False,
1119        "where": False,
1120        "columns": False,
1121        "unique": False,
1122        "primary": False,
1123        "amp": False,  # teradata
1124    }
class Insert(Expression):
1127class Insert(Expression):
1128    arg_types = {
1129        "with": False,
1130        "this": True,
1131        "expression": False,
1132        "overwrite": False,
1133        "exists": False,
1134        "partition": False,
1135        "alternative": False,
1136    }
class Introducer(Expression):
1140class Introducer(Expression):
1141    arg_types = {"this": True, "expression": True}
class National(Expression):
1145class National(Expression):
1146    pass
class LoadData(Expression):
1149class LoadData(Expression):
1150    arg_types = {
1151        "this": True,
1152        "local": False,
1153        "overwrite": False,
1154        "inpath": True,
1155        "partition": False,
1156        "input_format": False,
1157        "serde": False,
1158    }
class Partition(Expression):
1161class Partition(Expression):
1162    arg_types = {"expressions": True}
class Fetch(Expression):
1165class Fetch(Expression):
1166    arg_types = {"direction": False, "count": False}
class Group(Expression):
1169class Group(Expression):
1170    arg_types = {
1171        "expressions": False,
1172        "grouping_sets": False,
1173        "cube": False,
1174        "rollup": False,
1175    }
class Lambda(Expression):
1178class Lambda(Expression):
1179    arg_types = {"this": True, "expressions": True}
class Limit(Expression):
1182class Limit(Expression):
1183    arg_types = {"this": False, "expression": True}
class Literal(Condition):
1186class Literal(Condition):
1187    arg_types = {"this": True, "is_string": True}
1188
1189    def __eq__(self, other):
1190        return (
1191            isinstance(other, Literal)
1192            and self.this == other.this
1193            and self.args["is_string"] == other.args["is_string"]
1194        )
1195
1196    def __hash__(self):
1197        return hash((self.key, self.this, self.args["is_string"]))
1198
1199    @classmethod
1200    def number(cls, number) -> Literal:
1201        return cls(this=str(number), is_string=False)
1202
1203    @classmethod
1204    def string(cls, string) -> Literal:
1205        return cls(this=str(string), is_string=True)
1206
1207    @property
1208    def output_name(self):
1209        return self.name
@classmethod
def number(cls, number) -> sqlglot.expressions.Literal:
1199    @classmethod
1200    def number(cls, number) -> Literal:
1201        return cls(this=str(number), is_string=False)
@classmethod
def string(cls, string) -> sqlglot.expressions.Literal:
1203    @classmethod
1204    def string(cls, string) -> Literal:
1205        return cls(this=str(string), is_string=True)
output_name

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
class Join(Expression):
1212class Join(Expression):
1213    arg_types = {
1214        "this": True,
1215        "on": False,
1216        "side": False,
1217        "kind": False,
1218        "using": False,
1219        "natural": False,
1220    }
1221
1222    @property
1223    def kind(self):
1224        return self.text("kind").upper()
1225
1226    @property
1227    def side(self):
1228        return self.text("side").upper()
1229
1230    @property
1231    def alias_or_name(self):
1232        return self.this.alias_or_name
1233
1234    def on(self, *expressions, append=True, dialect=None, copy=True, **opts):
1235        """
1236        Append to or set the ON expressions.
1237
1238        Example:
1239            >>> import sqlglot
1240            >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql()
1241            'JOIN x ON y = 1'
1242
1243        Args:
1244            *expressions (str | Expression): the SQL code strings to parse.
1245                If an `Expression` instance is passed, it will be used as-is.
1246                Multiple expressions are combined with an AND operator.
1247            append (bool): if `True`, AND the new expressions to any existing expression.
1248                Otherwise, this resets the expression.
1249            dialect (str): the dialect used to parse the input expressions.
1250            copy (bool): if `False`, modify this expression instance in-place.
1251            opts (kwargs): other options to use to parse the input expressions.
1252
1253        Returns:
1254            Join: the modified join expression.
1255        """
1256        join = _apply_conjunction_builder(
1257            *expressions,
1258            instance=self,
1259            arg="on",
1260            append=append,
1261            dialect=dialect,
1262            copy=copy,
1263            **opts,
1264        )
1265
1266        if join.kind == "CROSS":
1267            join.set("kind", None)
1268
1269        return join
1270
1271    def using(self, *expressions, append=True, dialect=None, copy=True, **opts):
1272        """
1273        Append to or set the USING expressions.
1274
1275        Example:
1276            >>> import sqlglot
1277            >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql()
1278            'JOIN x USING (foo, bla)'
1279
1280        Args:
1281            *expressions (str | Expression): the SQL code strings to parse.
1282                If an `Expression` instance is passed, it will be used as-is.
1283            append (bool): if `True`, concatenate the new expressions to the existing "using" list.
1284                Otherwise, this resets the expression.
1285            dialect (str): the dialect used to parse the input expressions.
1286            copy (bool): if `False`, modify this expression instance in-place.
1287            opts (kwargs): other options to use to parse the input expressions.
1288
1289        Returns:
1290            Join: the modified join expression.
1291        """
1292        join = _apply_list_builder(
1293            *expressions,
1294            instance=self,
1295            arg="using",
1296            append=append,
1297            dialect=dialect,
1298            copy=copy,
1299            **opts,
1300        )
1301
1302        if join.kind == "CROSS":
1303            join.set("kind", None)
1304
1305        return join
def on(self, *expressions, append=True, dialect=None, copy=True, **opts):
1234    def on(self, *expressions, append=True, dialect=None, copy=True, **opts):
1235        """
1236        Append to or set the ON expressions.
1237
1238        Example:
1239            >>> import sqlglot
1240            >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql()
1241            'JOIN x ON y = 1'
1242
1243        Args:
1244            *expressions (str | Expression): the SQL code strings to parse.
1245                If an `Expression` instance is passed, it will be used as-is.
1246                Multiple expressions are combined with an AND operator.
1247            append (bool): if `True`, AND the new expressions to any existing expression.
1248                Otherwise, this resets the expression.
1249            dialect (str): the dialect used to parse the input expressions.
1250            copy (bool): if `False`, modify this expression instance in-place.
1251            opts (kwargs): other options to use to parse the input expressions.
1252
1253        Returns:
1254            Join: the modified join expression.
1255        """
1256        join = _apply_conjunction_builder(
1257            *expressions,
1258            instance=self,
1259            arg="on",
1260            append=append,
1261            dialect=dialect,
1262            copy=copy,
1263            **opts,
1264        )
1265
1266        if join.kind == "CROSS":
1267            join.set("kind", None)
1268
1269        return join

Append to or set the ON expressions.

Example:
>>> import sqlglot
>>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql()
'JOIN x ON y = 1'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, it will be used as-is. Multiple expressions are combined with an AND operator.
  • append (bool): if True, AND the new expressions to any existing expression. Otherwise, this resets the expression.
  • dialect (str): the dialect used to parse the input expressions.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Join: the modified join expression.

def using(self, *expressions, append=True, dialect=None, copy=True, **opts):
1271    def using(self, *expressions, append=True, dialect=None, copy=True, **opts):
1272        """
1273        Append to or set the USING expressions.
1274
1275        Example:
1276            >>> import sqlglot
1277            >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql()
1278            'JOIN x USING (foo, bla)'
1279
1280        Args:
1281            *expressions (str | Expression): the SQL code strings to parse.
1282                If an `Expression` instance is passed, it will be used as-is.
1283            append (bool): if `True`, concatenate the new expressions to the existing "using" list.
1284                Otherwise, this resets the expression.
1285            dialect (str): the dialect used to parse the input expressions.
1286            copy (bool): if `False`, modify this expression instance in-place.
1287            opts (kwargs): other options to use to parse the input expressions.
1288
1289        Returns:
1290            Join: the modified join expression.
1291        """
1292        join = _apply_list_builder(
1293            *expressions,
1294            instance=self,
1295            arg="using",
1296            append=append,
1297            dialect=dialect,
1298            copy=copy,
1299            **opts,
1300        )
1301
1302        if join.kind == "CROSS":
1303            join.set("kind", None)
1304
1305        return join

Append to or set the USING expressions.

Example:
>>> import sqlglot
>>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql()
'JOIN x USING (foo, bla)'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • append (bool): if True, concatenate the new expressions to the existing "using" list. Otherwise, this resets the expression.
  • dialect (str): the dialect used to parse the input expressions.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Join: the modified join expression.

class Lateral(UDTF):
1308class Lateral(UDTF):
1309    arg_types = {"this": True, "view": False, "outer": False, "alias": False}
class MatchRecognize(Expression):
1312class MatchRecognize(Expression):
1313    arg_types = {
1314        "partition_by": False,
1315        "order": False,
1316        "measures": False,
1317        "rows": False,
1318        "after": False,
1319        "pattern": False,
1320        "define": False,
1321    }
class Final(Expression):
1326class Final(Expression):
1327    pass
class Offset(Expression):
1330class Offset(Expression):
1331    arg_types = {"this": False, "expression": True}
class Order(Expression):
1334class Order(Expression):
1335    arg_types = {"this": False, "expressions": True}
class Cluster(Order):
1340class Cluster(Order):
1341    pass
class Distribute(Order):
1344class Distribute(Order):
1345    pass
class Sort(Order):
1348class Sort(Order):
1349    pass
class Ordered(Expression):
1352class Ordered(Expression):
1353    arg_types = {"this": True, "desc": True, "nulls_first": True}
class Property(Expression):
1356class Property(Expression):
1357    arg_types = {"this": True, "value": True}
class AfterJournalProperty(Property):
1360class AfterJournalProperty(Property):
1361    arg_types = {"no": True, "dual": False, "local": False}
class AlgorithmProperty(Property):
1364class AlgorithmProperty(Property):
1365    arg_types = {"this": True}
class AutoIncrementProperty(Property):
1368class AutoIncrementProperty(Property):
1369    arg_types = {"this": True}
class BlockCompressionProperty(Property):
1372class BlockCompressionProperty(Property):
1373    arg_types = {"autotemp": False, "always": False, "default": True, "manual": True, "never": True}
class CharacterSetProperty(Property):
1376class CharacterSetProperty(Property):
1377    arg_types = {"this": True, "default": True}
class ChecksumProperty(Property):
1380class ChecksumProperty(Property):
1381    arg_types = {"on": False, "default": False}
class CollateProperty(Property):
1384class CollateProperty(Property):
1385    arg_types = {"this": True}
class DataBlocksizeProperty(Property):
1388class DataBlocksizeProperty(Property):
1389    arg_types = {"size": False, "units": False, "min": False, "default": False}
class DefinerProperty(Property):
1392class DefinerProperty(Property):
1393    arg_types = {"this": True}
class DistKeyProperty(Property):
1396class DistKeyProperty(Property):
1397    arg_types = {"this": True}
class DistStyleProperty(Property):
1400class DistStyleProperty(Property):
1401    arg_types = {"this": True}
class EngineProperty(Property):
1404class EngineProperty(Property):
1405    arg_types = {"this": True}
class ExecuteAsProperty(Property):
1408class ExecuteAsProperty(Property):
1409    arg_types = {"this": True}
class ExternalProperty(Property):
1412class ExternalProperty(Property):
1413    arg_types = {"this": False}
class FallbackProperty(Property):
1416class FallbackProperty(Property):
1417    arg_types = {"no": True, "protection": False}
class FileFormatProperty(Property):
1420class FileFormatProperty(Property):
1421    arg_types = {"this": True}
class FreespaceProperty(Property):
1424class FreespaceProperty(Property):
1425    arg_types = {"this": True, "percent": False}
class IsolatedLoadingProperty(Property):
1428class IsolatedLoadingProperty(Property):
1429    arg_types = {
1430        "no": True,
1431        "concurrent": True,
1432        "for_all": True,
1433        "for_insert": True,
1434        "for_none": True,
1435    }
class JournalProperty(Property):
1438class JournalProperty(Property):
1439    arg_types = {"no": True, "dual": False, "before": False}
class LanguageProperty(Property):
1442class LanguageProperty(Property):
1443    arg_types = {"this": True}
class LikeProperty(Property):
1446class LikeProperty(Property):
1447    arg_types = {"this": True, "expressions": False}
class LocationProperty(Property):
1450class LocationProperty(Property):
1451    arg_types = {"this": True}
class LockingProperty(Property):
1454class LockingProperty(Property):
1455    arg_types = {
1456        "this": False,
1457        "kind": True,
1458        "for_or_in": True,
1459        "lock_type": True,
1460        "override": False,
1461    }
class LogProperty(Property):
1464class LogProperty(Property):
1465    arg_types = {"no": True}
class MaterializedProperty(Property):
1468class MaterializedProperty(Property):
1469    arg_types = {"this": False}
class MergeBlockRatioProperty(Property):
1472class MergeBlockRatioProperty(Property):
1473    arg_types = {"this": False, "no": False, "default": False, "percent": False}
class NoPrimaryIndexProperty(Property):
1476class NoPrimaryIndexProperty(Property):
1477    arg_types = {"this": False}
class OnCommitProperty(Property):
1480class OnCommitProperty(Property):
1481    arg_type = {"this": False}
class PartitionedByProperty(Property):
1484class PartitionedByProperty(Property):
1485    arg_types = {"this": True}
class ReturnsProperty(Property):
1488class ReturnsProperty(Property):
1489    arg_types = {"this": True, "is_table": False, "table": False}
class RowFormatDelimitedProperty(Property):
1492class RowFormatDelimitedProperty(Property):
1493    # https://cwiki.apache.org/confluence/display/hive/languagemanual+dml
1494    arg_types = {
1495        "fields": False,
1496        "escaped": False,
1497        "collection_items": False,
1498        "map_keys": False,
1499        "lines": False,
1500        "null": False,
1501        "serde": False,
1502    }
class RowFormatSerdeProperty(Property):
1505class RowFormatSerdeProperty(Property):
1506    arg_types = {"this": True}
class SchemaCommentProperty(Property):
1509class SchemaCommentProperty(Property):
1510    arg_types = {"this": True}
class SerdeProperties(Property):
1513class SerdeProperties(Property):
1514    arg_types = {"expressions": True}
class SetProperty(Property):
1517class SetProperty(Property):
1518    arg_types = {"multi": True}
class SortKeyProperty(Property):
1521class SortKeyProperty(Property):
1522    arg_types = {"this": True, "compound": False}
class SqlSecurityProperty(Property):
1525class SqlSecurityProperty(Property):
1526    arg_types = {"definer": True}
class TableFormatProperty(Property):
1529class TableFormatProperty(Property):
1530    arg_types = {"this": True}
class TemporaryProperty(Property):
1533class TemporaryProperty(Property):
1534    arg_types = {"global_": True}
class TransientProperty(Property):
1537class TransientProperty(Property):
1538    arg_types = {"this": False}
class VolatilityProperty(Property):
1541class VolatilityProperty(Property):
1542    arg_types = {"this": True}
class WithDataProperty(Property):
1545class WithDataProperty(Property):
1546    arg_types = {"no": True, "statistics": False}
class WithJournalTableProperty(Property):
1549class WithJournalTableProperty(Property):
1550    arg_types = {"this": True}
class Properties(Expression):
1553class Properties(Expression):
1554    arg_types = {"expressions": True}
1555
1556    NAME_TO_PROPERTY = {
1557        "ALGORITHM": AlgorithmProperty,
1558        "AUTO_INCREMENT": AutoIncrementProperty,
1559        "CHARACTER SET": CharacterSetProperty,
1560        "COLLATE": CollateProperty,
1561        "COMMENT": SchemaCommentProperty,
1562        "DEFINER": DefinerProperty,
1563        "DISTKEY": DistKeyProperty,
1564        "DISTSTYLE": DistStyleProperty,
1565        "ENGINE": EngineProperty,
1566        "EXECUTE AS": ExecuteAsProperty,
1567        "FORMAT": FileFormatProperty,
1568        "LANGUAGE": LanguageProperty,
1569        "LOCATION": LocationProperty,
1570        "PARTITIONED_BY": PartitionedByProperty,
1571        "RETURNS": ReturnsProperty,
1572        "SORTKEY": SortKeyProperty,
1573        "TABLE_FORMAT": TableFormatProperty,
1574    }
1575
1576    PROPERTY_TO_NAME = {v: k for k, v in NAME_TO_PROPERTY.items()}
1577
1578    # CREATE property locations
1579    # Form: schema specified
1580    #   create [POST_CREATE]
1581    #     table a [POST_NAME]
1582    #     (b int) [POST_SCHEMA]
1583    #     with ([POST_WITH])
1584    #     index (b) [POST_INDEX]
1585    #
1586    # Form: alias selection
1587    #   create [POST_CREATE]
1588    #     table a [POST_NAME]
1589    #     as [POST_ALIAS] (select * from b) [POST_EXPRESSION]
1590    #     index (c) [POST_INDEX]
1591    class Location(AutoName):
1592        POST_CREATE = auto()
1593        POST_NAME = auto()
1594        POST_SCHEMA = auto()
1595        POST_WITH = auto()
1596        POST_ALIAS = auto()
1597        POST_EXPRESSION = auto()
1598        POST_INDEX = auto()
1599        UNSUPPORTED = auto()
1600
1601    @classmethod
1602    def from_dict(cls, properties_dict) -> Properties:
1603        expressions = []
1604        for key, value in properties_dict.items():
1605            property_cls = cls.NAME_TO_PROPERTY.get(key.upper())
1606            if property_cls:
1607                expressions.append(property_cls(this=convert(value)))
1608            else:
1609                expressions.append(Property(this=Literal.string(key), value=convert(value)))
1610
1611        return cls(expressions=expressions)
@classmethod
def from_dict(cls, properties_dict) -> sqlglot.expressions.Properties:
1601    @classmethod
1602    def from_dict(cls, properties_dict) -> Properties:
1603        expressions = []
1604        for key, value in properties_dict.items():
1605            property_cls = cls.NAME_TO_PROPERTY.get(key.upper())
1606            if property_cls:
1607                expressions.append(property_cls(this=convert(value)))
1608            else:
1609                expressions.append(Property(this=Literal.string(key), value=convert(value)))
1610
1611        return cls(expressions=expressions)
class Properties.Location(sqlglot.helper.AutoName):
1591    class Location(AutoName):
1592        POST_CREATE = auto()
1593        POST_NAME = auto()
1594        POST_SCHEMA = auto()
1595        POST_WITH = auto()
1596        POST_ALIAS = auto()
1597        POST_EXPRESSION = auto()
1598        POST_INDEX = auto()
1599        UNSUPPORTED = auto()

An enumeration.

POST_CREATE = <Location.POST_CREATE: 'POST_CREATE'>
POST_NAME = <Location.POST_NAME: 'POST_NAME'>
POST_SCHEMA = <Location.POST_SCHEMA: 'POST_SCHEMA'>
POST_WITH = <Location.POST_WITH: 'POST_WITH'>
POST_ALIAS = <Location.POST_ALIAS: 'POST_ALIAS'>
POST_EXPRESSION = <Location.POST_EXPRESSION: 'POST_EXPRESSION'>
POST_INDEX = <Location.POST_INDEX: 'POST_INDEX'>
UNSUPPORTED = <Location.UNSUPPORTED: 'UNSUPPORTED'>
Inherited Members
enum.Enum
name
value
class Qualify(Expression):
1614class Qualify(Expression):
1615    pass
class Return(Expression):
1619class Return(Expression):
1620    pass
class Reference(Expression):
1623class Reference(Expression):
1624    arg_types = {"this": True, "expressions": False, "options": False}
class Tuple(Expression):
1627class Tuple(Expression):
1628    arg_types = {"expressions": False}
class Subqueryable(Unionable):
1631class Subqueryable(Unionable):
1632    def subquery(self, alias=None, copy=True) -> Subquery:
1633        """
1634        Convert this expression to an aliased expression that can be used as a Subquery.
1635
1636        Example:
1637            >>> subquery = Select().select("x").from_("tbl").subquery()
1638            >>> Select().select("x").from_(subquery).sql()
1639            'SELECT x FROM (SELECT x FROM tbl)'
1640
1641        Args:
1642            alias (str | Identifier): an optional alias for the subquery
1643            copy (bool): if `False`, modify this expression instance in-place.
1644
1645        Returns:
1646            Alias: the subquery
1647        """
1648        instance = _maybe_copy(self, copy)
1649        return Subquery(
1650            this=instance,
1651            alias=TableAlias(this=to_identifier(alias)),
1652        )
1653
1654    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
1655        raise NotImplementedError
1656
1657    @property
1658    def ctes(self):
1659        with_ = self.args.get("with")
1660        if not with_:
1661            return []
1662        return with_.expressions
1663
1664    @property
1665    def selects(self):
1666        raise NotImplementedError("Subqueryable objects must implement `selects`")
1667
1668    @property
1669    def named_selects(self):
1670        raise NotImplementedError("Subqueryable objects must implement `named_selects`")
1671
1672    def with_(
1673        self,
1674        alias,
1675        as_,
1676        recursive=None,
1677        append=True,
1678        dialect=None,
1679        copy=True,
1680        **opts,
1681    ):
1682        """
1683        Append to or set the common table expressions.
1684
1685        Example:
1686            >>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql()
1687            'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2'
1688
1689        Args:
1690            alias (str | Expression): the SQL code string to parse as the table name.
1691                If an `Expression` instance is passed, this is used as-is.
1692            as_ (str | Expression): the SQL code string to parse as the table expression.
1693                If an `Expression` instance is passed, it will be used as-is.
1694            recursive (bool): set the RECURSIVE part of the expression. Defaults to `False`.
1695            append (bool): if `True`, add to any existing expressions.
1696                Otherwise, this resets the expressions.
1697            dialect (str): the dialect used to parse the input expression.
1698            copy (bool): if `False`, modify this expression instance in-place.
1699            opts (kwargs): other options to use to parse the input expressions.
1700
1701        Returns:
1702            Select: the modified expression.
1703        """
1704        alias_expression = maybe_parse(
1705            alias,
1706            dialect=dialect,
1707            into=TableAlias,
1708            **opts,
1709        )
1710        as_expression = maybe_parse(
1711            as_,
1712            dialect=dialect,
1713            **opts,
1714        )
1715        cte = CTE(
1716            this=as_expression,
1717            alias=alias_expression,
1718        )
1719        return _apply_child_list_builder(
1720            cte,
1721            instance=self,
1722            arg="with",
1723            append=append,
1724            copy=copy,
1725            into=With,
1726            properties={"recursive": recursive or False},
1727        )
def subquery(self, alias=None, copy=True) -> sqlglot.expressions.Subquery:
1632    def subquery(self, alias=None, copy=True) -> Subquery:
1633        """
1634        Convert this expression to an aliased expression that can be used as a Subquery.
1635
1636        Example:
1637            >>> subquery = Select().select("x").from_("tbl").subquery()
1638            >>> Select().select("x").from_(subquery).sql()
1639            'SELECT x FROM (SELECT x FROM tbl)'
1640
1641        Args:
1642            alias (str | Identifier): an optional alias for the subquery
1643            copy (bool): if `False`, modify this expression instance in-place.
1644
1645        Returns:
1646            Alias: the subquery
1647        """
1648        instance = _maybe_copy(self, copy)
1649        return Subquery(
1650            this=instance,
1651            alias=TableAlias(this=to_identifier(alias)),
1652        )

Convert this expression to an aliased expression that can be used as a Subquery.

Example:
>>> subquery = Select().select("x").from_("tbl").subquery()
>>> Select().select("x").from_(subquery).sql()
'SELECT x FROM (SELECT x FROM tbl)'
Arguments:
  • alias (str | Identifier): an optional alias for the subquery
  • copy (bool): if False, modify this expression instance in-place.
Returns:

Alias: the subquery

def limit( self, expression, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
1654    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
1655        raise NotImplementedError
def with_( self, alias, as_, recursive=None, append=True, dialect=None, copy=True, **opts):
1672    def with_(
1673        self,
1674        alias,
1675        as_,
1676        recursive=None,
1677        append=True,
1678        dialect=None,
1679        copy=True,
1680        **opts,
1681    ):
1682        """
1683        Append to or set the common table expressions.
1684
1685        Example:
1686            >>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql()
1687            'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2'
1688
1689        Args:
1690            alias (str | Expression): the SQL code string to parse as the table name.
1691                If an `Expression` instance is passed, this is used as-is.
1692            as_ (str | Expression): the SQL code string to parse as the table expression.
1693                If an `Expression` instance is passed, it will be used as-is.
1694            recursive (bool): set the RECURSIVE part of the expression. Defaults to `False`.
1695            append (bool): if `True`, add to any existing expressions.
1696                Otherwise, this resets the expressions.
1697            dialect (str): the dialect used to parse the input expression.
1698            copy (bool): if `False`, modify this expression instance in-place.
1699            opts (kwargs): other options to use to parse the input expressions.
1700
1701        Returns:
1702            Select: the modified expression.
1703        """
1704        alias_expression = maybe_parse(
1705            alias,
1706            dialect=dialect,
1707            into=TableAlias,
1708            **opts,
1709        )
1710        as_expression = maybe_parse(
1711            as_,
1712            dialect=dialect,
1713            **opts,
1714        )
1715        cte = CTE(
1716            this=as_expression,
1717            alias=alias_expression,
1718        )
1719        return _apply_child_list_builder(
1720            cte,
1721            instance=self,
1722            arg="with",
1723            append=append,
1724            copy=copy,
1725            into=With,
1726            properties={"recursive": recursive or False},
1727        )

Append to or set the common table expressions.

Example:
>>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql()
'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2'
Arguments:
  • alias (str | Expression): the SQL code string to parse as the table name. If an Expression instance is passed, this is used as-is.
  • as_ (str | Expression): the SQL code string to parse as the table expression. If an Expression instance is passed, it will be used as-is.
  • recursive (bool): set the RECURSIVE part of the expression. Defaults to False.
  • append (bool): if True, add to any existing expressions. Otherwise, this resets the expressions.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

class Table(Expression):
1750class Table(Expression):
1751    arg_types = {
1752        "this": True,
1753        "alias": False,
1754        "db": False,
1755        "catalog": False,
1756        "laterals": False,
1757        "joins": False,
1758        "pivots": False,
1759        "hints": False,
1760        "system_time": False,
1761    }
1762
1763    @property
1764    def db(self) -> str:
1765        return self.text("db")
1766
1767    @property
1768    def catalog(self) -> str:
1769        return self.text("catalog")
class SystemTime(Expression):
1773class SystemTime(Expression):
1774    arg_types = {
1775        "this": False,
1776        "expression": False,
1777        "kind": True,
1778    }
class Union(Subqueryable):
1781class Union(Subqueryable):
1782    arg_types = {
1783        "with": False,
1784        "this": True,
1785        "expression": True,
1786        "distinct": False,
1787        **QUERY_MODIFIERS,
1788    }
1789
1790    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
1791        """
1792        Set the LIMIT expression.
1793
1794        Example:
1795            >>> select("1").union(select("1")).limit(1).sql()
1796            'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1'
1797
1798        Args:
1799            expression (str | int | Expression): the SQL code string to parse.
1800                This can also be an integer.
1801                If a `Limit` instance is passed, this is used as-is.
1802                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
1803            dialect (str): the dialect used to parse the input expression.
1804            copy (bool): if `False`, modify this expression instance in-place.
1805            opts (kwargs): other options to use to parse the input expressions.
1806
1807        Returns:
1808            Select: The limited subqueryable.
1809        """
1810        return (
1811            select("*")
1812            .from_(self.subquery(alias="_l_0", copy=copy))
1813            .limit(expression, dialect=dialect, copy=False, **opts)
1814        )
1815
1816    def select(
1817        self,
1818        *expressions: str | Expression,
1819        append: bool = True,
1820        dialect: DialectType = None,
1821        copy: bool = True,
1822        **opts,
1823    ) -> Union:
1824        """Append to or set the SELECT of the union recursively.
1825
1826        Example:
1827            >>> from sqlglot import parse_one
1828            >>> parse_one("select a from x union select a from y union select a from z").select("b").sql()
1829            'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z'
1830
1831        Args:
1832            *expressions: the SQL code strings to parse.
1833                If an `Expression` instance is passed, it will be used as-is.
1834            append: if `True`, add to any existing expressions.
1835                Otherwise, this resets the expressions.
1836            dialect: the dialect used to parse the input expressions.
1837            copy: if `False`, modify this expression instance in-place.
1838            opts: other options to use to parse the input expressions.
1839
1840        Returns:
1841            Union: the modified expression.
1842        """
1843        this = self.copy() if copy else self
1844        this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts)
1845        this.expression.unnest().select(
1846            *expressions, append=append, dialect=dialect, copy=False, **opts
1847        )
1848        return this
1849
1850    @property
1851    def named_selects(self):
1852        return self.this.unnest().named_selects
1853
1854    @property
1855    def is_star(self) -> bool:
1856        return self.this.is_star or self.expression.is_star
1857
1858    @property
1859    def selects(self):
1860        return self.this.unnest().selects
1861
1862    @property
1863    def left(self):
1864        return self.this
1865
1866    @property
1867    def right(self):
1868        return self.expression
def limit( self, expression, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
1790    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
1791        """
1792        Set the LIMIT expression.
1793
1794        Example:
1795            >>> select("1").union(select("1")).limit(1).sql()
1796            'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1'
1797
1798        Args:
1799            expression (str | int | Expression): the SQL code string to parse.
1800                This can also be an integer.
1801                If a `Limit` instance is passed, this is used as-is.
1802                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
1803            dialect (str): the dialect used to parse the input expression.
1804            copy (bool): if `False`, modify this expression instance in-place.
1805            opts (kwargs): other options to use to parse the input expressions.
1806
1807        Returns:
1808            Select: The limited subqueryable.
1809        """
1810        return (
1811            select("*")
1812            .from_(self.subquery(alias="_l_0", copy=copy))
1813            .limit(expression, dialect=dialect, copy=False, **opts)
1814        )

Set the LIMIT expression.

Example:
>>> select("1").union(select("1")).limit(1).sql()
'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1'
Arguments:
  • expression (str | int | Expression): the SQL code string to parse. This can also be an integer. If a Limit instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Limit.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: The limited subqueryable.

def select( self, *expressions: str | sqlglot.expressions.Expression, append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> sqlglot.expressions.Union:
1816    def select(
1817        self,
1818        *expressions: str | Expression,
1819        append: bool = True,
1820        dialect: DialectType = None,
1821        copy: bool = True,
1822        **opts,
1823    ) -> Union:
1824        """Append to or set the SELECT of the union recursively.
1825
1826        Example:
1827            >>> from sqlglot import parse_one
1828            >>> parse_one("select a from x union select a from y union select a from z").select("b").sql()
1829            'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z'
1830
1831        Args:
1832            *expressions: the SQL code strings to parse.
1833                If an `Expression` instance is passed, it will be used as-is.
1834            append: if `True`, add to any existing expressions.
1835                Otherwise, this resets the expressions.
1836            dialect: the dialect used to parse the input expressions.
1837            copy: if `False`, modify this expression instance in-place.
1838            opts: other options to use to parse the input expressions.
1839
1840        Returns:
1841            Union: the modified expression.
1842        """
1843        this = self.copy() if copy else self
1844        this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts)
1845        this.expression.unnest().select(
1846            *expressions, append=append, dialect=dialect, copy=False, **opts
1847        )
1848        return this

Append to or set the SELECT of the union recursively.

Example:
>>> from sqlglot import parse_one
>>> parse_one("select a from x union select a from y union select a from z").select("b").sql()
'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z'
Arguments:
  • *expressions: the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • append: if True, add to any existing expressions. Otherwise, this resets the expressions.
  • dialect: the dialect used to parse the input expressions.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

Union: the modified expression.

is_star: bool

Checks whether an expression is a star.

class Except(Union):
1871class Except(Union):
1872    pass
class Intersect(Union):
1875class Intersect(Union):
1876    pass
class Unnest(UDTF):
1879class Unnest(UDTF):
1880    arg_types = {
1881        "expressions": True,
1882        "ordinality": False,
1883        "alias": False,
1884        "offset": False,
1885    }
class Update(Expression):
1888class Update(Expression):
1889    arg_types = {
1890        "with": False,
1891        "this": False,
1892        "expressions": True,
1893        "from": False,
1894        "where": False,
1895    }
class Values(UDTF):
1898class Values(UDTF):
1899    arg_types = {
1900        "expressions": True,
1901        "ordinality": False,
1902        "alias": False,
1903    }
class Var(Expression):
1906class Var(Expression):
1907    pass
class Schema(Expression):
1910class Schema(Expression):
1911    arg_types = {"this": False, "expressions": False}
class Lock(Expression):
1916class Lock(Expression):
1917    arg_types = {"update": True}
class Select(Subqueryable):
1920class Select(Subqueryable):
1921    arg_types = {
1922        "with": False,
1923        "expressions": False,
1924        "hint": False,
1925        "distinct": False,
1926        "into": False,
1927        "from": False,
1928        **QUERY_MODIFIERS,
1929    }
1930
1931    def from_(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1932        """
1933        Set the FROM expression.
1934
1935        Example:
1936            >>> Select().from_("tbl").select("x").sql()
1937            'SELECT x FROM tbl'
1938
1939        Args:
1940            *expressions (str | Expression): the SQL code strings to parse.
1941                If a `From` instance is passed, this is used as-is.
1942                If another `Expression` instance is passed, it will be wrapped in a `From`.
1943            append (bool): if `True`, add to any existing expressions.
1944                Otherwise, this flattens all the `From` expression into a single expression.
1945            dialect (str): the dialect used to parse the input expression.
1946            copy (bool): if `False`, modify this expression instance in-place.
1947            opts (kwargs): other options to use to parse the input expressions.
1948
1949        Returns:
1950            Select: the modified expression.
1951        """
1952        return _apply_child_list_builder(
1953            *expressions,
1954            instance=self,
1955            arg="from",
1956            append=append,
1957            copy=copy,
1958            prefix="FROM",
1959            into=From,
1960            dialect=dialect,
1961            **opts,
1962        )
1963
1964    def group_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1965        """
1966        Set the GROUP BY expression.
1967
1968        Example:
1969            >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql()
1970            'SELECT x, COUNT(1) FROM tbl GROUP BY x'
1971
1972        Args:
1973            *expressions (str | Expression): the SQL code strings to parse.
1974                If a `Group` instance is passed, this is used as-is.
1975                If another `Expression` instance is passed, it will be wrapped in a `Group`.
1976                If nothing is passed in then a group by is not applied to the expression
1977            append (bool): if `True`, add to any existing expressions.
1978                Otherwise, this flattens all the `Group` expression into a single expression.
1979            dialect (str): the dialect used to parse the input expression.
1980            copy (bool): if `False`, modify this expression instance in-place.
1981            opts (kwargs): other options to use to parse the input expressions.
1982
1983        Returns:
1984            Select: the modified expression.
1985        """
1986        if not expressions:
1987            return self if not copy else self.copy()
1988        return _apply_child_list_builder(
1989            *expressions,
1990            instance=self,
1991            arg="group",
1992            append=append,
1993            copy=copy,
1994            prefix="GROUP BY",
1995            into=Group,
1996            dialect=dialect,
1997            **opts,
1998        )
1999
2000    def order_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2001        """
2002        Set the ORDER BY expression.
2003
2004        Example:
2005            >>> Select().from_("tbl").select("x").order_by("x DESC").sql()
2006            'SELECT x FROM tbl ORDER BY x DESC'
2007
2008        Args:
2009            *expressions (str | Expression): the SQL code strings to parse.
2010                If a `Group` instance is passed, this is used as-is.
2011                If another `Expression` instance is passed, it will be wrapped in a `Order`.
2012            append (bool): if `True`, add to any existing expressions.
2013                Otherwise, this flattens all the `Order` expression into a single expression.
2014            dialect (str): the dialect used to parse the input expression.
2015            copy (bool): if `False`, modify this expression instance in-place.
2016            opts (kwargs): other options to use to parse the input expressions.
2017
2018        Returns:
2019            Select: the modified expression.
2020        """
2021        return _apply_child_list_builder(
2022            *expressions,
2023            instance=self,
2024            arg="order",
2025            append=append,
2026            copy=copy,
2027            prefix="ORDER BY",
2028            into=Order,
2029            dialect=dialect,
2030            **opts,
2031        )
2032
2033    def sort_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2034        """
2035        Set the SORT BY expression.
2036
2037        Example:
2038            >>> Select().from_("tbl").select("x").sort_by("x DESC").sql()
2039            'SELECT x FROM tbl SORT BY x DESC'
2040
2041        Args:
2042            *expressions (str | Expression): the SQL code strings to parse.
2043                If a `Group` instance is passed, this is used as-is.
2044                If another `Expression` instance is passed, it will be wrapped in a `SORT`.
2045            append (bool): if `True`, add to any existing expressions.
2046                Otherwise, this flattens all the `Order` expression into a single expression.
2047            dialect (str): the dialect used to parse the input expression.
2048            copy (bool): if `False`, modify this expression instance in-place.
2049            opts (kwargs): other options to use to parse the input expressions.
2050
2051        Returns:
2052            Select: the modified expression.
2053        """
2054        return _apply_child_list_builder(
2055            *expressions,
2056            instance=self,
2057            arg="sort",
2058            append=append,
2059            copy=copy,
2060            prefix="SORT BY",
2061            into=Sort,
2062            dialect=dialect,
2063            **opts,
2064        )
2065
2066    def cluster_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2067        """
2068        Set the CLUSTER BY expression.
2069
2070        Example:
2071            >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql()
2072            'SELECT x FROM tbl CLUSTER BY x DESC'
2073
2074        Args:
2075            *expressions (str | Expression): the SQL code strings to parse.
2076                If a `Group` instance is passed, this is used as-is.
2077                If another `Expression` instance is passed, it will be wrapped in a `Cluster`.
2078            append (bool): if `True`, add to any existing expressions.
2079                Otherwise, this flattens all the `Order` expression into a single expression.
2080            dialect (str): the dialect used to parse the input expression.
2081            copy (bool): if `False`, modify this expression instance in-place.
2082            opts (kwargs): other options to use to parse the input expressions.
2083
2084        Returns:
2085            Select: the modified expression.
2086        """
2087        return _apply_child_list_builder(
2088            *expressions,
2089            instance=self,
2090            arg="cluster",
2091            append=append,
2092            copy=copy,
2093            prefix="CLUSTER BY",
2094            into=Cluster,
2095            dialect=dialect,
2096            **opts,
2097        )
2098
2099    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
2100        """
2101        Set the LIMIT expression.
2102
2103        Example:
2104            >>> Select().from_("tbl").select("x").limit(10).sql()
2105            'SELECT x FROM tbl LIMIT 10'
2106
2107        Args:
2108            expression (str | int | Expression): the SQL code string to parse.
2109                This can also be an integer.
2110                If a `Limit` instance is passed, this is used as-is.
2111                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
2112            dialect (str): the dialect used to parse the input expression.
2113            copy (bool): if `False`, modify this expression instance in-place.
2114            opts (kwargs): other options to use to parse the input expressions.
2115
2116        Returns:
2117            Select: the modified expression.
2118        """
2119        return _apply_builder(
2120            expression=expression,
2121            instance=self,
2122            arg="limit",
2123            into=Limit,
2124            prefix="LIMIT",
2125            dialect=dialect,
2126            copy=copy,
2127            **opts,
2128        )
2129
2130    def offset(self, expression, dialect=None, copy=True, **opts) -> Select:
2131        """
2132        Set the OFFSET expression.
2133
2134        Example:
2135            >>> Select().from_("tbl").select("x").offset(10).sql()
2136            'SELECT x FROM tbl OFFSET 10'
2137
2138        Args:
2139            expression (str | int | Expression): the SQL code string to parse.
2140                This can also be an integer.
2141                If a `Offset` instance is passed, this is used as-is.
2142                If another `Expression` instance is passed, it will be wrapped in a `Offset`.
2143            dialect (str): the dialect used to parse the input expression.
2144            copy (bool): if `False`, modify this expression instance in-place.
2145            opts (kwargs): other options to use to parse the input expressions.
2146
2147        Returns:
2148            Select: the modified expression.
2149        """
2150        return _apply_builder(
2151            expression=expression,
2152            instance=self,
2153            arg="offset",
2154            into=Offset,
2155            prefix="OFFSET",
2156            dialect=dialect,
2157            copy=copy,
2158            **opts,
2159        )
2160
2161    def select(
2162        self,
2163        *expressions: str | Expression,
2164        append: bool = True,
2165        dialect: DialectType = None,
2166        copy: bool = True,
2167        **opts,
2168    ) -> Select:
2169        """
2170        Append to or set the SELECT expressions.
2171
2172        Example:
2173            >>> Select().select("x", "y").sql()
2174            'SELECT x, y'
2175
2176        Args:
2177            *expressions: the SQL code strings to parse.
2178                If an `Expression` instance is passed, it will be used as-is.
2179            append: if `True`, add to any existing expressions.
2180                Otherwise, this resets the expressions.
2181            dialect: the dialect used to parse the input expressions.
2182            copy: if `False`, modify this expression instance in-place.
2183            opts: other options to use to parse the input expressions.
2184
2185        Returns:
2186            Select: the modified expression.
2187        """
2188        return _apply_list_builder(
2189            *expressions,
2190            instance=self,
2191            arg="expressions",
2192            append=append,
2193            dialect=dialect,
2194            copy=copy,
2195            **opts,
2196        )
2197
2198    def lateral(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2199        """
2200        Append to or set the LATERAL expressions.
2201
2202        Example:
2203            >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql()
2204            'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
2205
2206        Args:
2207            *expressions (str | Expression): the SQL code strings to parse.
2208                If an `Expression` instance is passed, it will be used as-is.
2209            append (bool): if `True`, add to any existing expressions.
2210                Otherwise, this resets the expressions.
2211            dialect (str): the dialect used to parse the input expressions.
2212            copy (bool): if `False`, modify this expression instance in-place.
2213            opts (kwargs): other options to use to parse the input expressions.
2214
2215        Returns:
2216            Select: the modified expression.
2217        """
2218        return _apply_list_builder(
2219            *expressions,
2220            instance=self,
2221            arg="laterals",
2222            append=append,
2223            into=Lateral,
2224            prefix="LATERAL VIEW",
2225            dialect=dialect,
2226            copy=copy,
2227            **opts,
2228        )
2229
2230    def join(
2231        self,
2232        expression,
2233        on=None,
2234        using=None,
2235        append=True,
2236        join_type=None,
2237        join_alias=None,
2238        dialect=None,
2239        copy=True,
2240        **opts,
2241    ) -> Select:
2242        """
2243        Append to or set the JOIN expressions.
2244
2245        Example:
2246            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql()
2247            'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'
2248
2249            >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql()
2250            'SELECT 1 FROM a JOIN b USING (x, y, z)'
2251
2252            Use `join_type` to change the type of join:
2253
2254            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql()
2255            'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
2256
2257        Args:
2258            expression (str | Expression): the SQL code string to parse.
2259                If an `Expression` instance is passed, it will be used as-is.
2260            on (str | Expression): optionally specify the join "on" criteria as a SQL string.
2261                If an `Expression` instance is passed, it will be used as-is.
2262            using (str | Expression): optionally specify the join "using" criteria as a SQL string.
2263                If an `Expression` instance is passed, it will be used as-is.
2264            append (bool): if `True`, add to any existing expressions.
2265                Otherwise, this resets the expressions.
2266            join_type (str): If set, alter the parsed join type
2267            dialect (str): the dialect used to parse the input expressions.
2268            copy (bool): if `False`, modify this expression instance in-place.
2269            opts (kwargs): other options to use to parse the input expressions.
2270
2271        Returns:
2272            Select: the modified expression.
2273        """
2274        parse_args = {"dialect": dialect, **opts}
2275
2276        try:
2277            expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args)
2278        except ParseError:
2279            expression = maybe_parse(expression, into=(Join, Expression), **parse_args)
2280
2281        join = expression if isinstance(expression, Join) else Join(this=expression)
2282
2283        if isinstance(join.this, Select):
2284            join.this.replace(join.this.subquery())
2285
2286        if join_type:
2287            natural: t.Optional[Token]
2288            side: t.Optional[Token]
2289            kind: t.Optional[Token]
2290
2291            natural, side, kind = maybe_parse(join_type, into="JOIN_TYPE", **parse_args)  # type: ignore
2292
2293            if natural:
2294                join.set("natural", True)
2295            if side:
2296                join.set("side", side.text)
2297            if kind:
2298                join.set("kind", kind.text)
2299
2300        if on:
2301            on = and_(*ensure_collection(on), dialect=dialect, **opts)
2302            join.set("on", on)
2303
2304        if using:
2305            join = _apply_list_builder(
2306                *ensure_collection(using),
2307                instance=join,
2308                arg="using",
2309                append=append,
2310                copy=copy,
2311                **opts,
2312            )
2313
2314        if join_alias:
2315            join.set("this", alias_(join.this, join_alias, table=True))
2316        return _apply_list_builder(
2317            join,
2318            instance=self,
2319            arg="joins",
2320            append=append,
2321            copy=copy,
2322            **opts,
2323        )
2324
2325    def where(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2326        """
2327        Append to or set the WHERE expressions.
2328
2329        Example:
2330            >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql()
2331            "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
2332
2333        Args:
2334            *expressions (str | Expression): the SQL code strings to parse.
2335                If an `Expression` instance is passed, it will be used as-is.
2336                Multiple expressions are combined with an AND operator.
2337            append (bool): if `True`, AND the new expressions to any existing expression.
2338                Otherwise, this resets the expression.
2339            dialect (str): the dialect used to parse the input expressions.
2340            copy (bool): if `False`, modify this expression instance in-place.
2341            opts (kwargs): other options to use to parse the input expressions.
2342
2343        Returns:
2344            Select: the modified expression.
2345        """
2346        return _apply_conjunction_builder(
2347            *expressions,
2348            instance=self,
2349            arg="where",
2350            append=append,
2351            into=Where,
2352            dialect=dialect,
2353            copy=copy,
2354            **opts,
2355        )
2356
2357    def having(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2358        """
2359        Append to or set the HAVING expressions.
2360
2361        Example:
2362            >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql()
2363            'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
2364
2365        Args:
2366            *expressions (str | Expression): the SQL code strings to parse.
2367                If an `Expression` instance is passed, it will be used as-is.
2368                Multiple expressions are combined with an AND operator.
2369            append (bool): if `True`, AND the new expressions to any existing expression.
2370                Otherwise, this resets the expression.
2371            dialect (str): the dialect used to parse the input expressions.
2372            copy (bool): if `False`, modify this expression instance in-place.
2373            opts (kwargs): other options to use to parse the input expressions.
2374
2375        Returns:
2376            Select: the modified expression.
2377        """
2378        return _apply_conjunction_builder(
2379            *expressions,
2380            instance=self,
2381            arg="having",
2382            append=append,
2383            into=Having,
2384            dialect=dialect,
2385            copy=copy,
2386            **opts,
2387        )
2388
2389    def window(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2390        return _apply_list_builder(
2391            *expressions,
2392            instance=self,
2393            arg="windows",
2394            append=append,
2395            into=Window,
2396            dialect=dialect,
2397            copy=copy,
2398            **opts,
2399        )
2400
2401    def distinct(self, distinct=True, copy=True) -> Select:
2402        """
2403        Set the OFFSET expression.
2404
2405        Example:
2406            >>> Select().from_("tbl").select("x").distinct().sql()
2407            'SELECT DISTINCT x FROM tbl'
2408
2409        Args:
2410            distinct (bool): whether the Select should be distinct
2411            copy (bool): if `False`, modify this expression instance in-place.
2412
2413        Returns:
2414            Select: the modified expression.
2415        """
2416        instance = _maybe_copy(self, copy)
2417        instance.set("distinct", Distinct() if distinct else None)
2418        return instance
2419
2420    def ctas(self, table, properties=None, dialect=None, copy=True, **opts) -> Create:
2421        """
2422        Convert this expression to a CREATE TABLE AS statement.
2423
2424        Example:
2425            >>> Select().select("*").from_("tbl").ctas("x").sql()
2426            'CREATE TABLE x AS SELECT * FROM tbl'
2427
2428        Args:
2429            table (str | Expression): the SQL code string to parse as the table name.
2430                If another `Expression` instance is passed, it will be used as-is.
2431            properties (dict): an optional mapping of table properties
2432            dialect (str): the dialect used to parse the input table.
2433            copy (bool): if `False`, modify this expression instance in-place.
2434            opts (kwargs): other options to use to parse the input table.
2435
2436        Returns:
2437            Create: the CREATE TABLE AS expression
2438        """
2439        instance = _maybe_copy(self, copy)
2440        table_expression = maybe_parse(
2441            table,
2442            into=Table,
2443            dialect=dialect,
2444            **opts,
2445        )
2446        properties_expression = None
2447        if properties:
2448            properties_expression = Properties.from_dict(properties)
2449
2450        return Create(
2451            this=table_expression,
2452            kind="table",
2453            expression=instance,
2454            properties=properties_expression,
2455        )
2456
2457    def lock(self, update: bool = True, copy: bool = True) -> Select:
2458        """
2459        Set the locking read mode for this expression.
2460
2461        Examples:
2462            >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql")
2463            "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE"
2464
2465            >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql")
2466            "SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
2467
2468        Args:
2469            update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`.
2470            copy: if `False`, modify this expression instance in-place.
2471
2472        Returns:
2473            The modified expression.
2474        """
2475
2476        inst = _maybe_copy(self, copy)
2477        inst.set("lock", Lock(update=update))
2478
2479        return inst
2480
2481    @property
2482    def named_selects(self) -> t.List[str]:
2483        return [e.output_name for e in self.expressions if e.alias_or_name]
2484
2485    @property
2486    def is_star(self) -> bool:
2487        return any(expression.is_star for expression in self.expressions)
2488
2489    @property
2490    def selects(self) -> t.List[Expression]:
2491        return self.expressions
def from_( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
1931    def from_(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1932        """
1933        Set the FROM expression.
1934
1935        Example:
1936            >>> Select().from_("tbl").select("x").sql()
1937            'SELECT x FROM tbl'
1938
1939        Args:
1940            *expressions (str | Expression): the SQL code strings to parse.
1941                If a `From` instance is passed, this is used as-is.
1942                If another `Expression` instance is passed, it will be wrapped in a `From`.
1943            append (bool): if `True`, add to any existing expressions.
1944                Otherwise, this flattens all the `From` expression into a single expression.
1945            dialect (str): the dialect used to parse the input expression.
1946            copy (bool): if `False`, modify this expression instance in-place.
1947            opts (kwargs): other options to use to parse the input expressions.
1948
1949        Returns:
1950            Select: the modified expression.
1951        """
1952        return _apply_child_list_builder(
1953            *expressions,
1954            instance=self,
1955            arg="from",
1956            append=append,
1957            copy=copy,
1958            prefix="FROM",
1959            into=From,
1960            dialect=dialect,
1961            **opts,
1962        )

Set the FROM expression.

Example:
>>> Select().from_("tbl").select("x").sql()
'SELECT x FROM tbl'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If a From instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a From.
  • append (bool): if True, add to any existing expressions. Otherwise, this flattens all the From expression into a single expression.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def group_by( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
1964    def group_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1965        """
1966        Set the GROUP BY expression.
1967
1968        Example:
1969            >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql()
1970            'SELECT x, COUNT(1) FROM tbl GROUP BY x'
1971
1972        Args:
1973            *expressions (str | Expression): the SQL code strings to parse.
1974                If a `Group` instance is passed, this is used as-is.
1975                If another `Expression` instance is passed, it will be wrapped in a `Group`.
1976                If nothing is passed in then a group by is not applied to the expression
1977            append (bool): if `True`, add to any existing expressions.
1978                Otherwise, this flattens all the `Group` expression into a single expression.
1979            dialect (str): the dialect used to parse the input expression.
1980            copy (bool): if `False`, modify this expression instance in-place.
1981            opts (kwargs): other options to use to parse the input expressions.
1982
1983        Returns:
1984            Select: the modified expression.
1985        """
1986        if not expressions:
1987            return self if not copy else self.copy()
1988        return _apply_child_list_builder(
1989            *expressions,
1990            instance=self,
1991            arg="group",
1992            append=append,
1993            copy=copy,
1994            prefix="GROUP BY",
1995            into=Group,
1996            dialect=dialect,
1997            **opts,
1998        )

Set the GROUP BY expression.

Example:
>>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql()
'SELECT x, COUNT(1) FROM tbl GROUP BY x'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If a Group instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Group. If nothing is passed in then a group by is not applied to the expression
  • append (bool): if True, add to any existing expressions. Otherwise, this flattens all the Group expression into a single expression.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def order_by( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2000    def order_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2001        """
2002        Set the ORDER BY expression.
2003
2004        Example:
2005            >>> Select().from_("tbl").select("x").order_by("x DESC").sql()
2006            'SELECT x FROM tbl ORDER BY x DESC'
2007
2008        Args:
2009            *expressions (str | Expression): the SQL code strings to parse.
2010                If a `Group` instance is passed, this is used as-is.
2011                If another `Expression` instance is passed, it will be wrapped in a `Order`.
2012            append (bool): if `True`, add to any existing expressions.
2013                Otherwise, this flattens all the `Order` expression into a single expression.
2014            dialect (str): the dialect used to parse the input expression.
2015            copy (bool): if `False`, modify this expression instance in-place.
2016            opts (kwargs): other options to use to parse the input expressions.
2017
2018        Returns:
2019            Select: the modified expression.
2020        """
2021        return _apply_child_list_builder(
2022            *expressions,
2023            instance=self,
2024            arg="order",
2025            append=append,
2026            copy=copy,
2027            prefix="ORDER BY",
2028            into=Order,
2029            dialect=dialect,
2030            **opts,
2031        )

Set the ORDER BY expression.

Example:
>>> Select().from_("tbl").select("x").order_by("x DESC").sql()
'SELECT x FROM tbl ORDER BY x DESC'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If a Group instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Order.
  • append (bool): if True, add to any existing expressions. Otherwise, this flattens all the Order expression into a single expression.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def sort_by( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2033    def sort_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2034        """
2035        Set the SORT BY expression.
2036
2037        Example:
2038            >>> Select().from_("tbl").select("x").sort_by("x DESC").sql()
2039            'SELECT x FROM tbl SORT BY x DESC'
2040
2041        Args:
2042            *expressions (str | Expression): the SQL code strings to parse.
2043                If a `Group` instance is passed, this is used as-is.
2044                If another `Expression` instance is passed, it will be wrapped in a `SORT`.
2045            append (bool): if `True`, add to any existing expressions.
2046                Otherwise, this flattens all the `Order` expression into a single expression.
2047            dialect (str): the dialect used to parse the input expression.
2048            copy (bool): if `False`, modify this expression instance in-place.
2049            opts (kwargs): other options to use to parse the input expressions.
2050
2051        Returns:
2052            Select: the modified expression.
2053        """
2054        return _apply_child_list_builder(
2055            *expressions,
2056            instance=self,
2057            arg="sort",
2058            append=append,
2059            copy=copy,
2060            prefix="SORT BY",
2061            into=Sort,
2062            dialect=dialect,
2063            **opts,
2064        )

Set the SORT BY expression.

Example:
>>> Select().from_("tbl").select("x").sort_by("x DESC").sql()
'SELECT x FROM tbl SORT BY x DESC'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If a Group instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a SORT.
  • append (bool): if True, add to any existing expressions. Otherwise, this flattens all the Order expression into a single expression.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def cluster_by( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2066    def cluster_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2067        """
2068        Set the CLUSTER BY expression.
2069
2070        Example:
2071            >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql()
2072            'SELECT x FROM tbl CLUSTER BY x DESC'
2073
2074        Args:
2075            *expressions (str | Expression): the SQL code strings to parse.
2076                If a `Group` instance is passed, this is used as-is.
2077                If another `Expression` instance is passed, it will be wrapped in a `Cluster`.
2078            append (bool): if `True`, add to any existing expressions.
2079                Otherwise, this flattens all the `Order` expression into a single expression.
2080            dialect (str): the dialect used to parse the input expression.
2081            copy (bool): if `False`, modify this expression instance in-place.
2082            opts (kwargs): other options to use to parse the input expressions.
2083
2084        Returns:
2085            Select: the modified expression.
2086        """
2087        return _apply_child_list_builder(
2088            *expressions,
2089            instance=self,
2090            arg="cluster",
2091            append=append,
2092            copy=copy,
2093            prefix="CLUSTER BY",
2094            into=Cluster,
2095            dialect=dialect,
2096            **opts,
2097        )

Set the CLUSTER BY expression.

Example:
>>> Select().from_("tbl").select("x").cluster_by("x DESC").sql()
'SELECT x FROM tbl CLUSTER BY x DESC'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If a Group instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Cluster.
  • append (bool): if True, add to any existing expressions. Otherwise, this flattens all the Order expression into a single expression.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def limit( self, expression, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2099    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
2100        """
2101        Set the LIMIT expression.
2102
2103        Example:
2104            >>> Select().from_("tbl").select("x").limit(10).sql()
2105            'SELECT x FROM tbl LIMIT 10'
2106
2107        Args:
2108            expression (str | int | Expression): the SQL code string to parse.
2109                This can also be an integer.
2110                If a `Limit` instance is passed, this is used as-is.
2111                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
2112            dialect (str): the dialect used to parse the input expression.
2113            copy (bool): if `False`, modify this expression instance in-place.
2114            opts (kwargs): other options to use to parse the input expressions.
2115
2116        Returns:
2117            Select: the modified expression.
2118        """
2119        return _apply_builder(
2120            expression=expression,
2121            instance=self,
2122            arg="limit",
2123            into=Limit,
2124            prefix="LIMIT",
2125            dialect=dialect,
2126            copy=copy,
2127            **opts,
2128        )

Set the LIMIT expression.

Example:
>>> Select().from_("tbl").select("x").limit(10).sql()
'SELECT x FROM tbl LIMIT 10'
Arguments:
  • expression (str | int | Expression): the SQL code string to parse. This can also be an integer. If a Limit instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Limit.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def offset( self, expression, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2130    def offset(self, expression, dialect=None, copy=True, **opts) -> Select:
2131        """
2132        Set the OFFSET expression.
2133
2134        Example:
2135            >>> Select().from_("tbl").select("x").offset(10).sql()
2136            'SELECT x FROM tbl OFFSET 10'
2137
2138        Args:
2139            expression (str | int | Expression): the SQL code string to parse.
2140                This can also be an integer.
2141                If a `Offset` instance is passed, this is used as-is.
2142                If another `Expression` instance is passed, it will be wrapped in a `Offset`.
2143            dialect (str): the dialect used to parse the input expression.
2144            copy (bool): if `False`, modify this expression instance in-place.
2145            opts (kwargs): other options to use to parse the input expressions.
2146
2147        Returns:
2148            Select: the modified expression.
2149        """
2150        return _apply_builder(
2151            expression=expression,
2152            instance=self,
2153            arg="offset",
2154            into=Offset,
2155            prefix="OFFSET",
2156            dialect=dialect,
2157            copy=copy,
2158            **opts,
2159        )

Set the OFFSET expression.

Example:
>>> Select().from_("tbl").select("x").offset(10).sql()
'SELECT x FROM tbl OFFSET 10'
Arguments:
  • expression (str | int | Expression): the SQL code string to parse. This can also be an integer. If a Offset instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Offset.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def select( self, *expressions: str | sqlglot.expressions.Expression, append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> sqlglot.expressions.Select:
2161    def select(
2162        self,
2163        *expressions: str | Expression,
2164        append: bool = True,
2165        dialect: DialectType = None,
2166        copy: bool = True,
2167        **opts,
2168    ) -> Select:
2169        """
2170        Append to or set the SELECT expressions.
2171
2172        Example:
2173            >>> Select().select("x", "y").sql()
2174            'SELECT x, y'
2175
2176        Args:
2177            *expressions: the SQL code strings to parse.
2178                If an `Expression` instance is passed, it will be used as-is.
2179            append: if `True`, add to any existing expressions.
2180                Otherwise, this resets the expressions.
2181            dialect: the dialect used to parse the input expressions.
2182            copy: if `False`, modify this expression instance in-place.
2183            opts: other options to use to parse the input expressions.
2184
2185        Returns:
2186            Select: the modified expression.
2187        """
2188        return _apply_list_builder(
2189            *expressions,
2190            instance=self,
2191            arg="expressions",
2192            append=append,
2193            dialect=dialect,
2194            copy=copy,
2195            **opts,
2196        )

Append to or set the SELECT expressions.

Example:
>>> Select().select("x", "y").sql()
'SELECT x, y'
Arguments:
  • *expressions: the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • append: if True, add to any existing expressions. Otherwise, this resets the expressions.
  • dialect: the dialect used to parse the input expressions.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def lateral( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2198    def lateral(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2199        """
2200        Append to or set the LATERAL expressions.
2201
2202        Example:
2203            >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql()
2204            'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
2205
2206        Args:
2207            *expressions (str | Expression): the SQL code strings to parse.
2208                If an `Expression` instance is passed, it will be used as-is.
2209            append (bool): if `True`, add to any existing expressions.
2210                Otherwise, this resets the expressions.
2211            dialect (str): the dialect used to parse the input expressions.
2212            copy (bool): if `False`, modify this expression instance in-place.
2213            opts (kwargs): other options to use to parse the input expressions.
2214
2215        Returns:
2216            Select: the modified expression.
2217        """
2218        return _apply_list_builder(
2219            *expressions,
2220            instance=self,
2221            arg="laterals",
2222            append=append,
2223            into=Lateral,
2224            prefix="LATERAL VIEW",
2225            dialect=dialect,
2226            copy=copy,
2227            **opts,
2228        )

Append to or set the LATERAL expressions.

Example:
>>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql()
'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • append (bool): if True, add to any existing expressions. Otherwise, this resets the expressions.
  • dialect (str): the dialect used to parse the input expressions.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def join( self, expression, on=None, using=None, append=True, join_type=None, join_alias=None, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2230    def join(
2231        self,
2232        expression,
2233        on=None,
2234        using=None,
2235        append=True,
2236        join_type=None,
2237        join_alias=None,
2238        dialect=None,
2239        copy=True,
2240        **opts,
2241    ) -> Select:
2242        """
2243        Append to or set the JOIN expressions.
2244
2245        Example:
2246            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql()
2247            'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'
2248
2249            >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql()
2250            'SELECT 1 FROM a JOIN b USING (x, y, z)'
2251
2252            Use `join_type` to change the type of join:
2253
2254            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql()
2255            'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
2256
2257        Args:
2258            expression (str | Expression): the SQL code string to parse.
2259                If an `Expression` instance is passed, it will be used as-is.
2260            on (str | Expression): optionally specify the join "on" criteria as a SQL string.
2261                If an `Expression` instance is passed, it will be used as-is.
2262            using (str | Expression): optionally specify the join "using" criteria as a SQL string.
2263                If an `Expression` instance is passed, it will be used as-is.
2264            append (bool): if `True`, add to any existing expressions.
2265                Otherwise, this resets the expressions.
2266            join_type (str): If set, alter the parsed join type
2267            dialect (str): the dialect used to parse the input expressions.
2268            copy (bool): if `False`, modify this expression instance in-place.
2269            opts (kwargs): other options to use to parse the input expressions.
2270
2271        Returns:
2272            Select: the modified expression.
2273        """
2274        parse_args = {"dialect": dialect, **opts}
2275
2276        try:
2277            expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args)
2278        except ParseError:
2279            expression = maybe_parse(expression, into=(Join, Expression), **parse_args)
2280
2281        join = expression if isinstance(expression, Join) else Join(this=expression)
2282
2283        if isinstance(join.this, Select):
2284            join.this.replace(join.this.subquery())
2285
2286        if join_type:
2287            natural: t.Optional[Token]
2288            side: t.Optional[Token]
2289            kind: t.Optional[Token]
2290
2291            natural, side, kind = maybe_parse(join_type, into="JOIN_TYPE", **parse_args)  # type: ignore
2292
2293            if natural:
2294                join.set("natural", True)
2295            if side:
2296                join.set("side", side.text)
2297            if kind:
2298                join.set("kind", kind.text)
2299
2300        if on:
2301            on = and_(*ensure_collection(on), dialect=dialect, **opts)
2302            join.set("on", on)
2303
2304        if using:
2305            join = _apply_list_builder(
2306                *ensure_collection(using),
2307                instance=join,
2308                arg="using",
2309                append=append,
2310                copy=copy,
2311                **opts,
2312            )
2313
2314        if join_alias:
2315            join.set("this", alias_(join.this, join_alias, table=True))
2316        return _apply_list_builder(
2317            join,
2318            instance=self,
2319            arg="joins",
2320            append=append,
2321            copy=copy,
2322            **opts,
2323        )

Append to or set the JOIN expressions.

Example:
>>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql()
'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'
>>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql()
'SELECT 1 FROM a JOIN b USING (x, y, z)'

Use join_type to change the type of join:

>>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql()
'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
Arguments:
  • expression (str | Expression): the SQL code string to parse. If an Expression instance is passed, it will be used as-is.
  • on (str | Expression): optionally specify the join "on" criteria as a SQL string. If an Expression instance is passed, it will be used as-is.
  • using (str | Expression): optionally specify the join "using" criteria as a SQL string. If an Expression instance is passed, it will be used as-is.
  • append (bool): if True, add to any existing expressions. Otherwise, this resets the expressions.
  • join_type (str): If set, alter the parsed join type
  • dialect (str): the dialect used to parse the input expressions.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def where( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2325    def where(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2326        """
2327        Append to or set the WHERE expressions.
2328
2329        Example:
2330            >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql()
2331            "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
2332
2333        Args:
2334            *expressions (str | Expression): the SQL code strings to parse.
2335                If an `Expression` instance is passed, it will be used as-is.
2336                Multiple expressions are combined with an AND operator.
2337            append (bool): if `True`, AND the new expressions to any existing expression.
2338                Otherwise, this resets the expression.
2339            dialect (str): the dialect used to parse the input expressions.
2340            copy (bool): if `False`, modify this expression instance in-place.
2341            opts (kwargs): other options to use to parse the input expressions.
2342
2343        Returns:
2344            Select: the modified expression.
2345        """
2346        return _apply_conjunction_builder(
2347            *expressions,
2348            instance=self,
2349            arg="where",
2350            append=append,
2351            into=Where,
2352            dialect=dialect,
2353            copy=copy,
2354            **opts,
2355        )

Append to or set the WHERE expressions.

Example:
>>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql()
"SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, it will be used as-is. Multiple expressions are combined with an AND operator.
  • append (bool): if True, AND the new expressions to any existing expression. Otherwise, this resets the expression.
  • dialect (str): the dialect used to parse the input expressions.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def having( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2357    def having(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2358        """
2359        Append to or set the HAVING expressions.
2360
2361        Example:
2362            >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql()
2363            'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
2364
2365        Args:
2366            *expressions (str | Expression): the SQL code strings to parse.
2367                If an `Expression` instance is passed, it will be used as-is.
2368                Multiple expressions are combined with an AND operator.
2369            append (bool): if `True`, AND the new expressions to any existing expression.
2370                Otherwise, this resets the expression.
2371            dialect (str): the dialect used to parse the input expressions.
2372            copy (bool): if `False`, modify this expression instance in-place.
2373            opts (kwargs): other options to use to parse the input expressions.
2374
2375        Returns:
2376            Select: the modified expression.
2377        """
2378        return _apply_conjunction_builder(
2379            *expressions,
2380            instance=self,
2381            arg="having",
2382            append=append,
2383            into=Having,
2384            dialect=dialect,
2385            copy=copy,
2386            **opts,
2387        )

Append to or set the HAVING expressions.

Example:
>>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql()
'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, it will be used as-is. Multiple expressions are combined with an AND operator.
  • append (bool): if True, AND the new expressions to any existing expression. Otherwise, this resets the expression.
  • dialect (str): the dialect used to parse the input expressions.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def window( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2389    def window(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2390        return _apply_list_builder(
2391            *expressions,
2392            instance=self,
2393            arg="windows",
2394            append=append,
2395            into=Window,
2396            dialect=dialect,
2397            copy=copy,
2398            **opts,
2399        )
def distinct(self, distinct=True, copy=True) -> sqlglot.expressions.Select:
2401    def distinct(self, distinct=True, copy=True) -> Select:
2402        """
2403        Set the OFFSET expression.
2404
2405        Example:
2406            >>> Select().from_("tbl").select("x").distinct().sql()
2407            'SELECT DISTINCT x FROM tbl'
2408
2409        Args:
2410            distinct (bool): whether the Select should be distinct
2411            copy (bool): if `False`, modify this expression instance in-place.
2412
2413        Returns:
2414            Select: the modified expression.
2415        """
2416        instance = _maybe_copy(self, copy)
2417        instance.set("distinct", Distinct() if distinct else None)
2418        return instance

Set the OFFSET expression.

Example:
>>> Select().from_("tbl").select("x").distinct().sql()
'SELECT DISTINCT x FROM tbl'
Arguments:
  • distinct (bool): whether the Select should be distinct
  • copy (bool): if False, modify this expression instance in-place.
Returns:

Select: the modified expression.

def ctas( self, table, properties=None, dialect=None, copy=True, **opts) -> sqlglot.expressions.Create:
2420    def ctas(self, table, properties=None, dialect=None, copy=True, **opts) -> Create:
2421        """
2422        Convert this expression to a CREATE TABLE AS statement.
2423
2424        Example:
2425            >>> Select().select("*").from_("tbl").ctas("x").sql()
2426            'CREATE TABLE x AS SELECT * FROM tbl'
2427
2428        Args:
2429            table (str | Expression): the SQL code string to parse as the table name.
2430                If another `Expression` instance is passed, it will be used as-is.
2431            properties (dict): an optional mapping of table properties
2432            dialect (str): the dialect used to parse the input table.
2433            copy (bool): if `False`, modify this expression instance in-place.
2434            opts (kwargs): other options to use to parse the input table.
2435
2436        Returns:
2437            Create: the CREATE TABLE AS expression
2438        """
2439        instance = _maybe_copy(self, copy)
2440        table_expression = maybe_parse(
2441            table,
2442            into=Table,
2443            dialect=dialect,
2444            **opts,
2445        )
2446        properties_expression = None
2447        if properties:
2448            properties_expression = Properties.from_dict(properties)
2449
2450        return Create(
2451            this=table_expression,
2452            kind="table",
2453            expression=instance,
2454            properties=properties_expression,
2455        )

Convert this expression to a CREATE TABLE AS statement.

Example:
>>> Select().select("*").from_("tbl").ctas("x").sql()
'CREATE TABLE x AS SELECT * FROM tbl'
Arguments:
  • table (str | Expression): the SQL code string to parse as the table name. If another Expression instance is passed, it will be used as-is.
  • properties (dict): an optional mapping of table properties
  • dialect (str): the dialect used to parse the input table.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input table.
Returns:

Create: the CREATE TABLE AS expression

def lock( self, update: bool = True, copy: bool = True) -> sqlglot.expressions.Select:
2457    def lock(self, update: bool = True, copy: bool = True) -> Select:
2458        """
2459        Set the locking read mode for this expression.
2460
2461        Examples:
2462            >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql")
2463            "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE"
2464
2465            >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql")
2466            "SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
2467
2468        Args:
2469            update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`.
2470            copy: if `False`, modify this expression instance in-place.
2471
2472        Returns:
2473            The modified expression.
2474        """
2475
2476        inst = _maybe_copy(self, copy)
2477        inst.set("lock", Lock(update=update))
2478
2479        return inst

Set the locking read mode for this expression.

Examples:
>>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql")
"SELECT x FROM tbl WHERE x = 'a' FOR UPDATE"
>>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql")
"SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
Arguments:
  • update: if True, the locking type will be FOR UPDATE, else it will be FOR SHARE.
  • copy: if False, modify this expression instance in-place.
Returns:

The modified expression.

is_star: bool

Checks whether an expression is a star.

class Subquery(DerivedTable, Unionable):
2494class Subquery(DerivedTable, Unionable):
2495    arg_types = {
2496        "this": True,
2497        "alias": False,
2498        "with": False,
2499        **QUERY_MODIFIERS,
2500    }
2501
2502    def unnest(self):
2503        """
2504        Returns the first non subquery.
2505        """
2506        expression = self
2507        while isinstance(expression, Subquery):
2508            expression = expression.this
2509        return expression
2510
2511    @property
2512    def is_star(self) -> bool:
2513        return self.this.is_star
2514
2515    @property
2516    def output_name(self):
2517        return self.alias
def unnest(self):
2502    def unnest(self):
2503        """
2504        Returns the first non subquery.
2505        """
2506        expression = self
2507        while isinstance(expression, Subquery):
2508            expression = expression.this
2509        return expression

Returns the first non subquery.

is_star: bool

Checks whether an expression is a star.

output_name

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
class TableSample(Expression):
2520class TableSample(Expression):
2521    arg_types = {
2522        "this": False,
2523        "method": False,
2524        "bucket_numerator": False,
2525        "bucket_denominator": False,
2526        "bucket_field": False,
2527        "percent": False,
2528        "rows": False,
2529        "size": False,
2530        "seed": False,
2531    }
class Tag(Expression):
2534class Tag(Expression):
2535    """Tags are used for generating arbitrary sql like SELECT <span>x</span>."""
2536
2537    arg_types = {
2538        "this": False,
2539        "prefix": False,
2540        "postfix": False,
2541    }

Tags are used for generating arbitrary sql like SELECT x.

class Pivot(Expression):
2544class Pivot(Expression):
2545    arg_types = {
2546        "this": False,
2547        "alias": False,
2548        "expressions": True,
2549        "field": True,
2550        "unpivot": True,
2551    }
class Window(Expression):
2554class Window(Expression):
2555    arg_types = {
2556        "this": True,
2557        "partition_by": False,
2558        "order": False,
2559        "spec": False,
2560        "alias": False,
2561    }
class WindowSpec(Expression):
2564class WindowSpec(Expression):
2565    arg_types = {
2566        "kind": False,
2567        "start": False,
2568        "start_side": False,
2569        "end": False,
2570        "end_side": False,
2571    }
class Where(Expression):
2574class Where(Expression):
2575    pass
class Star(Expression):
2578class Star(Expression):
2579    arg_types = {"except": False, "replace": False}
2580
2581    @property
2582    def name(self) -> str:
2583        return "*"
2584
2585    @property
2586    def output_name(self):
2587        return self.name
output_name

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
class Parameter(Expression):
2590class Parameter(Expression):
2591    arg_types = {"this": True, "wrapped": False}
class SessionParameter(Expression):
2594class SessionParameter(Expression):
2595    arg_types = {"this": True, "kind": False}
class Placeholder(Expression):
2598class Placeholder(Expression):
2599    arg_types = {"this": False}
class Null(Condition):
2602class Null(Condition):
2603    arg_types: t.Dict[str, t.Any] = {}
2604
2605    @property
2606    def name(self) -> str:
2607        return "NULL"
class Boolean(Condition):
2610class Boolean(Condition):
2611    pass
class DataType(Expression):
2614class DataType(Expression):
2615    arg_types = {
2616        "this": True,
2617        "expressions": False,
2618        "nested": False,
2619        "values": False,
2620        "prefix": False,
2621    }
2622
2623    class Type(AutoName):
2624        CHAR = auto()
2625        NCHAR = auto()
2626        VARCHAR = auto()
2627        NVARCHAR = auto()
2628        TEXT = auto()
2629        MEDIUMTEXT = auto()
2630        LONGTEXT = auto()
2631        MEDIUMBLOB = auto()
2632        LONGBLOB = auto()
2633        BINARY = auto()
2634        VARBINARY = auto()
2635        INT = auto()
2636        TINYINT = auto()
2637        SMALLINT = auto()
2638        BIGINT = auto()
2639        FLOAT = auto()
2640        DOUBLE = auto()
2641        DECIMAL = auto()
2642        BOOLEAN = auto()
2643        JSON = auto()
2644        JSONB = auto()
2645        INTERVAL = auto()
2646        TIME = auto()
2647        TIMESTAMP = auto()
2648        TIMESTAMPTZ = auto()
2649        TIMESTAMPLTZ = auto()
2650        DATE = auto()
2651        DATETIME = auto()
2652        ARRAY = auto()
2653        MAP = auto()
2654        UUID = auto()
2655        GEOGRAPHY = auto()
2656        GEOMETRY = auto()
2657        STRUCT = auto()
2658        NULLABLE = auto()
2659        HLLSKETCH = auto()
2660        HSTORE = auto()
2661        SUPER = auto()
2662        SERIAL = auto()
2663        SMALLSERIAL = auto()
2664        BIGSERIAL = auto()
2665        XML = auto()
2666        UNIQUEIDENTIFIER = auto()
2667        MONEY = auto()
2668        SMALLMONEY = auto()
2669        ROWVERSION = auto()
2670        IMAGE = auto()
2671        VARIANT = auto()
2672        OBJECT = auto()
2673        INET = auto()
2674        NULL = auto()
2675        UNKNOWN = auto()  # Sentinel value, useful for type annotation
2676
2677    TEXT_TYPES = {
2678        Type.CHAR,
2679        Type.NCHAR,
2680        Type.VARCHAR,
2681        Type.NVARCHAR,
2682        Type.TEXT,
2683    }
2684
2685    INTEGER_TYPES = {
2686        Type.INT,
2687        Type.TINYINT,
2688        Type.SMALLINT,
2689        Type.BIGINT,
2690    }
2691
2692    FLOAT_TYPES = {
2693        Type.FLOAT,
2694        Type.DOUBLE,
2695    }
2696
2697    NUMERIC_TYPES = {*INTEGER_TYPES, *FLOAT_TYPES}
2698
2699    TEMPORAL_TYPES = {
2700        Type.TIMESTAMP,
2701        Type.TIMESTAMPTZ,
2702        Type.TIMESTAMPLTZ,
2703        Type.DATE,
2704        Type.DATETIME,
2705    }
2706
2707    @classmethod
2708    def build(
2709        cls, dtype: str | DataType | DataType.Type, dialect: DialectType = None, **kwargs
2710    ) -> DataType:
2711        from sqlglot import parse_one
2712
2713        if isinstance(dtype, str):
2714            if dtype.upper() in cls.Type.__members__:
2715                data_type_exp: t.Optional[Expression] = DataType(this=DataType.Type[dtype.upper()])
2716            else:
2717                data_type_exp = parse_one(dtype, read=dialect, into=DataType)
2718            if data_type_exp is None:
2719                raise ValueError(f"Unparsable data type value: {dtype}")
2720        elif isinstance(dtype, DataType.Type):
2721            data_type_exp = DataType(this=dtype)
2722        elif isinstance(dtype, DataType):
2723            return dtype
2724        else:
2725            raise ValueError(f"Invalid data type: {type(dtype)}. Expected str or DataType.Type")
2726        return DataType(**{**data_type_exp.args, **kwargs})
2727
2728    def is_type(self, dtype: DataType.Type) -> bool:
2729        return self.this == dtype
@classmethod
def build( cls, dtype: str | sqlglot.expressions.DataType | sqlglot.expressions.DataType.Type, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **kwargs) -> sqlglot.expressions.DataType:
2707    @classmethod
2708    def build(
2709        cls, dtype: str | DataType | DataType.Type, dialect: DialectType = None, **kwargs
2710    ) -> DataType:
2711        from sqlglot import parse_one
2712
2713        if isinstance(dtype, str):
2714            if dtype.upper() in cls.Type.__members__:
2715                data_type_exp: t.Optional[Expression] = DataType(this=DataType.Type[dtype.upper()])
2716            else:
2717                data_type_exp = parse_one(dtype, read=dialect, into=DataType)
2718            if data_type_exp is None:
2719                raise ValueError(f"Unparsable data type value: {dtype}")
2720        elif isinstance(dtype, DataType.Type):
2721            data_type_exp = DataType(this=dtype)
2722        elif isinstance(dtype, DataType):
2723            return dtype
2724        else:
2725            raise ValueError(f"Invalid data type: {type(dtype)}. Expected str or DataType.Type")
2726        return DataType(**{**data_type_exp.args, **kwargs})
def is_type(self, dtype: sqlglot.expressions.DataType.Type) -> bool:
2728    def is_type(self, dtype: DataType.Type) -> bool:
2729        return self.this == dtype
class DataType.Type(sqlglot.helper.AutoName):
2623    class Type(AutoName):
2624        CHAR = auto()
2625        NCHAR = auto()
2626        VARCHAR = auto()
2627        NVARCHAR = auto()
2628        TEXT = auto()
2629        MEDIUMTEXT = auto()
2630        LONGTEXT = auto()
2631        MEDIUMBLOB = auto()
2632        LONGBLOB = auto()
2633        BINARY = auto()
2634        VARBINARY = auto()
2635        INT = auto()
2636        TINYINT = auto()
2637        SMALLINT = auto()
2638        BIGINT = auto()
2639        FLOAT = auto()
2640        DOUBLE = auto()
2641        DECIMAL = auto()
2642        BOOLEAN = auto()
2643        JSON = auto()
2644        JSONB = auto()
2645        INTERVAL = auto()
2646        TIME = auto()
2647        TIMESTAMP = auto()
2648        TIMESTAMPTZ = auto()
2649        TIMESTAMPLTZ = auto()
2650        DATE = auto()
2651        DATETIME = auto()
2652        ARRAY = auto()
2653        MAP = auto()
2654        UUID = auto()
2655        GEOGRAPHY = auto()
2656        GEOMETRY = auto()
2657        STRUCT = auto()
2658        NULLABLE = auto()
2659        HLLSKETCH = auto()
2660        HSTORE = auto()
2661        SUPER = auto()
2662        SERIAL = auto()
2663        SMALLSERIAL = auto()
2664        BIGSERIAL = auto()
2665        XML = auto()
2666        UNIQUEIDENTIFIER = auto()
2667        MONEY = auto()
2668        SMALLMONEY = auto()
2669        ROWVERSION = auto()
2670        IMAGE = auto()
2671        VARIANT = auto()
2672        OBJECT = auto()
2673        INET = auto()
2674        NULL = auto()
2675        UNKNOWN = auto()  # Sentinel value, useful for type annotation

An enumeration.

CHAR = <Type.CHAR: 'CHAR'>
NCHAR = <Type.NCHAR: 'NCHAR'>
VARCHAR = <Type.VARCHAR: 'VARCHAR'>
NVARCHAR = <Type.NVARCHAR: 'NVARCHAR'>
TEXT = <Type.TEXT: 'TEXT'>
MEDIUMTEXT = <Type.MEDIUMTEXT: 'MEDIUMTEXT'>
LONGTEXT = <Type.LONGTEXT: 'LONGTEXT'>
MEDIUMBLOB = <Type.MEDIUMBLOB: 'MEDIUMBLOB'>
LONGBLOB = <Type.LONGBLOB: 'LONGBLOB'>
BINARY = <Type.BINARY: 'BINARY'>
VARBINARY = <Type.VARBINARY: 'VARBINARY'>
INT = <Type.INT: 'INT'>
TINYINT = <Type.TINYINT: 'TINYINT'>
SMALLINT = <Type.SMALLINT: 'SMALLINT'>
BIGINT = <Type.BIGINT: 'BIGINT'>
FLOAT = <Type.FLOAT: 'FLOAT'>
DOUBLE = <Type.DOUBLE: 'DOUBLE'>
DECIMAL = <Type.DECIMAL: 'DECIMAL'>
BOOLEAN = <Type.BOOLEAN: 'BOOLEAN'>
JSON = <Type.JSON: 'JSON'>
JSONB = <Type.JSONB: 'JSONB'>
INTERVAL = <Type.INTERVAL: 'INTERVAL'>
TIME = <Type.TIME: 'TIME'>
TIMESTAMP = <Type.TIMESTAMP: 'TIMESTAMP'>
TIMESTAMPTZ = <Type.TIMESTAMPTZ: 'TIMESTAMPTZ'>
TIMESTAMPLTZ = <Type.TIMESTAMPLTZ: 'TIMESTAMPLTZ'>
DATE = <Type.DATE: 'DATE'>
DATETIME = <Type.DATETIME: 'DATETIME'>
ARRAY = <Type.ARRAY: 'ARRAY'>
MAP = <Type.MAP: 'MAP'>
UUID = <Type.UUID: 'UUID'>
GEOGRAPHY = <Type.GEOGRAPHY: 'GEOGRAPHY'>
GEOMETRY = <Type.GEOMETRY: 'GEOMETRY'>
STRUCT = <Type.STRUCT: 'STRUCT'>
NULLABLE = <Type.NULLABLE: 'NULLABLE'>
HLLSKETCH = <Type.HLLSKETCH: 'HLLSKETCH'>
HSTORE = <Type.HSTORE: 'HSTORE'>
SUPER = <Type.SUPER: 'SUPER'>
SERIAL = <Type.SERIAL: 'SERIAL'>
SMALLSERIAL = <Type.SMALLSERIAL: 'SMALLSERIAL'>
BIGSERIAL = <Type.BIGSERIAL: 'BIGSERIAL'>
XML = <Type.XML: 'XML'>
UNIQUEIDENTIFIER = <Type.UNIQUEIDENTIFIER: 'UNIQUEIDENTIFIER'>
MONEY = <Type.MONEY: 'MONEY'>
SMALLMONEY = <Type.SMALLMONEY: 'SMALLMONEY'>
ROWVERSION = <Type.ROWVERSION: 'ROWVERSION'>
IMAGE = <Type.IMAGE: 'IMAGE'>
VARIANT = <Type.VARIANT: 'VARIANT'>
OBJECT = <Type.OBJECT: 'OBJECT'>
INET = <Type.INET: 'INET'>
NULL = <Type.NULL: 'NULL'>
UNKNOWN = <Type.UNKNOWN: 'UNKNOWN'>
Inherited Members
enum.Enum
name
value
class PseudoType(Expression):
2733class PseudoType(Expression):
2734    pass
class StructKwarg(Expression):
2737class StructKwarg(Expression):
2738    arg_types = {"this": True, "expression": True}
class SubqueryPredicate(Predicate):
2742class SubqueryPredicate(Predicate):
2743    pass
class All(SubqueryPredicate):
2746class All(SubqueryPredicate):
2747    pass
class Any(SubqueryPredicate):
2750class Any(SubqueryPredicate):
2751    pass
class Exists(SubqueryPredicate):
2754class Exists(SubqueryPredicate):
2755    pass
class Command(Expression):
2760class Command(Expression):
2761    arg_types = {"this": True, "expression": False}
class Transaction(Expression):
2764class Transaction(Expression):
2765    arg_types = {"this": False, "modes": False}
class Commit(Expression):
2768class Commit(Expression):
2769    arg_types = {"chain": False}
class Rollback(Expression):
2772class Rollback(Expression):
2773    arg_types = {"savepoint": False}
class AlterTable(Expression):
2776class AlterTable(Expression):
2777    arg_types = {"this": True, "actions": True, "exists": False}
class AddConstraint(Expression):
2780class AddConstraint(Expression):
2781    arg_types = {"this": False, "expression": False, "enforced": False}
class DropPartition(Expression):
2784class DropPartition(Expression):
2785    arg_types = {"expressions": True, "exists": False}
class Binary(Expression):
2789class Binary(Expression):
2790    arg_types = {"this": True, "expression": True}
2791
2792    @property
2793    def left(self):
2794        return self.this
2795
2796    @property
2797    def right(self):
2798        return self.expression
class Add(Binary):
2801class Add(Binary):
2802    pass
class Connector(Binary, Condition):
2805class Connector(Binary, Condition):
2806    pass
class And(Connector):
2809class And(Connector):
2810    pass
class Or(Connector):
2813class Or(Connector):
2814    pass
class BitwiseAnd(Binary):
2817class BitwiseAnd(Binary):
2818    pass
class BitwiseLeftShift(Binary):
2821class BitwiseLeftShift(Binary):
2822    pass
class BitwiseOr(Binary):
2825class BitwiseOr(Binary):
2826    pass
class BitwiseRightShift(Binary):
2829class BitwiseRightShift(Binary):
2830    pass
class BitwiseXor(Binary):
2833class BitwiseXor(Binary):
2834    pass
class Div(Binary):
2837class Div(Binary):
2838    pass
class Overlaps(Binary):
2841class Overlaps(Binary):
2842    pass
class Dot(Binary):
2845class Dot(Binary):
2846    @property
2847    def name(self) -> str:
2848        return self.expression.name
class DPipe(Binary):
2851class DPipe(Binary):
2852    pass
class EQ(Binary, Predicate):
2855class EQ(Binary, Predicate):
2856    pass
class NullSafeEQ(Binary, Predicate):
2859class NullSafeEQ(Binary, Predicate):
2860    pass
class NullSafeNEQ(Binary, Predicate):
2863class NullSafeNEQ(Binary, Predicate):
2864    pass
class Distance(Binary):
2867class Distance(Binary):
2868    pass
class Escape(Binary):
2871class Escape(Binary):
2872    pass
class Glob(Binary, Predicate):
2875class Glob(Binary, Predicate):
2876    pass
class GT(Binary, Predicate):
2879class GT(Binary, Predicate):
2880    pass
class GTE(Binary, Predicate):
2883class GTE(Binary, Predicate):
2884    pass
class ILike(Binary, Predicate):
2887class ILike(Binary, Predicate):
2888    pass
class ILikeAny(Binary, Predicate):
2891class ILikeAny(Binary, Predicate):
2892    pass
class IntDiv(Binary):
2895class IntDiv(Binary):
2896    pass
class Is(Binary, Predicate):
2899class Is(Binary, Predicate):
2900    pass
class Kwarg(Binary):
2903class Kwarg(Binary):
2904    """Kwarg in special functions like func(kwarg => y)."""

Kwarg in special functions like func(kwarg => y).

class Like(Binary, Predicate):
2907class Like(Binary, Predicate):
2908    pass
class LikeAny(Binary, Predicate):
2911class LikeAny(Binary, Predicate):
2912    pass
class LT(Binary, Predicate):
2915class LT(Binary, Predicate):
2916    pass
class LTE(Binary, Predicate):
2919class LTE(Binary, Predicate):
2920    pass
class Mod(Binary):
2923class Mod(Binary):
2924    pass
class Mul(Binary):
2927class Mul(Binary):
2928    pass
class NEQ(Binary, Predicate):
2931class NEQ(Binary, Predicate):
2932    pass
class SimilarTo(Binary, Predicate):
2935class SimilarTo(Binary, Predicate):
2936    pass
class Slice(Binary):
2939class Slice(Binary):
2940    arg_types = {"this": False, "expression": False}
class Sub(Binary):
2943class Sub(Binary):
2944    pass
class Unary(Expression):
2949class Unary(Expression):
2950    pass
class BitwiseNot(Unary):
2953class BitwiseNot(Unary):
2954    pass
class Not(Unary, Condition):
2957class Not(Unary, Condition):
2958    pass
class Paren(Unary, Condition):
2961class Paren(Unary, Condition):
2962    arg_types = {"this": True, "with": False}
class Neg(Unary):
2965class Neg(Unary):
2966    pass
class Alias(Expression):
2970class Alias(Expression):
2971    arg_types = {"this": True, "alias": False}
2972
2973    @property
2974    def output_name(self):
2975        return self.alias
output_name

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
class Aliases(Expression):
2978class Aliases(Expression):
2979    arg_types = {"this": True, "expressions": True}
2980
2981    @property
2982    def aliases(self):
2983        return self.expressions
class AtTimeZone(Expression):
2986class AtTimeZone(Expression):
2987    arg_types = {"this": True, "zone": True}
class Between(Predicate):
2990class Between(Predicate):
2991    arg_types = {"this": True, "low": True, "high": True}
class Bracket(Condition):
2994class Bracket(Condition):
2995    arg_types = {"this": True, "expressions": True}
class Distinct(Expression):
2998class Distinct(Expression):
2999    arg_types = {"expressions": False, "on": False}
class In(Predicate):
3002class In(Predicate):
3003    arg_types = {
3004        "this": True,
3005        "expressions": False,
3006        "query": False,
3007        "unnest": False,
3008        "field": False,
3009        "is_global": False,
3010    }
class TimeUnit(Expression):
3013class TimeUnit(Expression):
3014    """Automatically converts unit arg into a var."""
3015
3016    arg_types = {"unit": False}
3017
3018    def __init__(self, **args):
3019        unit = args.get("unit")
3020        if isinstance(unit, Column):
3021            args["unit"] = Var(this=unit.name)
3022        elif isinstance(unit, Week):
3023            unit.set("this", Var(this=unit.this.name))
3024        super().__init__(**args)

Automatically converts unit arg into a var.

TimeUnit(**args)
3018    def __init__(self, **args):
3019        unit = args.get("unit")
3020        if isinstance(unit, Column):
3021            args["unit"] = Var(this=unit.name)
3022        elif isinstance(unit, Week):
3023            unit.set("this", Var(this=unit.this.name))
3024        super().__init__(**args)
class Interval(TimeUnit):
3027class Interval(TimeUnit):
3028    arg_types = {"this": False, "unit": False}
class IgnoreNulls(Expression):
3031class IgnoreNulls(Expression):
3032    pass
class RespectNulls(Expression):
3035class RespectNulls(Expression):
3036    pass
class Func(Condition):
3040class Func(Condition):
3041    """
3042    The base class for all function expressions.
3043
3044    Attributes:
3045        is_var_len_args (bool): if set to True the last argument defined in arg_types will be
3046            treated as a variable length argument and the argument's value will be stored as a list.
3047        _sql_names (list): determines the SQL name (1st item in the list) and aliases (subsequent items)
3048            for this function expression. These values are used to map this node to a name during parsing
3049            as well as to provide the function's name during SQL string generation. By default the SQL
3050            name is set to the expression's class name transformed to snake case.
3051    """
3052
3053    is_var_len_args = False
3054
3055    @classmethod
3056    def from_arg_list(cls, args):
3057        if cls.is_var_len_args:
3058            all_arg_keys = list(cls.arg_types)
3059            # If this function supports variable length argument treat the last argument as such.
3060            non_var_len_arg_keys = all_arg_keys[:-1] if cls.is_var_len_args else all_arg_keys
3061            num_non_var = len(non_var_len_arg_keys)
3062
3063            args_dict = {arg_key: arg for arg, arg_key in zip(args, non_var_len_arg_keys)}
3064            args_dict[all_arg_keys[-1]] = args[num_non_var:]
3065        else:
3066            args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)}
3067
3068        return cls(**args_dict)
3069
3070    @classmethod
3071    def sql_names(cls):
3072        if cls is Func:
3073            raise NotImplementedError(
3074                "SQL name is only supported by concrete function implementations"
3075            )
3076        if "_sql_names" not in cls.__dict__:
3077            cls._sql_names = [camel_to_snake_case(cls.__name__)]
3078        return cls._sql_names
3079
3080    @classmethod
3081    def sql_name(cls):
3082        return cls.sql_names()[0]
3083
3084    @classmethod
3085    def default_parser_mappings(cls):
3086        return {name: cls.from_arg_list for name in cls.sql_names()}

The base class for all function expressions.

Attributes:
  • is_var_len_args (bool): if set to True the last argument defined in arg_types will be treated as a variable length argument and the argument's value will be stored as a list.
  • _sql_names (list): determines the SQL name (1st item in the list) and aliases (subsequent items) for this function expression. These values are used to map this node to a name during parsing as well as to provide the function's name during SQL string generation. By default the SQL name is set to the expression's class name transformed to snake case.
@classmethod
def from_arg_list(cls, args):
3055    @classmethod
3056    def from_arg_list(cls, args):
3057        if cls.is_var_len_args:
3058            all_arg_keys = list(cls.arg_types)
3059            # If this function supports variable length argument treat the last argument as such.
3060            non_var_len_arg_keys = all_arg_keys[:-1] if cls.is_var_len_args else all_arg_keys
3061            num_non_var = len(non_var_len_arg_keys)
3062
3063            args_dict = {arg_key: arg for arg, arg_key in zip(args, non_var_len_arg_keys)}
3064            args_dict[all_arg_keys[-1]] = args[num_non_var:]
3065        else:
3066            args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)}
3067
3068        return cls(**args_dict)
@classmethod
def sql_names(cls):
3070    @classmethod
3071    def sql_names(cls):
3072        if cls is Func:
3073            raise NotImplementedError(
3074                "SQL name is only supported by concrete function implementations"
3075            )
3076        if "_sql_names" not in cls.__dict__:
3077            cls._sql_names = [camel_to_snake_case(cls.__name__)]
3078        return cls._sql_names
@classmethod
def sql_name(cls):
3080    @classmethod
3081    def sql_name(cls):
3082        return cls.sql_names()[0]
@classmethod
def default_parser_mappings(cls):
3084    @classmethod
3085    def default_parser_mappings(cls):
3086        return {name: cls.from_arg_list for name in cls.sql_names()}
class AggFunc(Func):
3089class AggFunc(Func):
3090    pass
class Abs(Func):
3093class Abs(Func):
3094    pass
class Anonymous(Func):
3097class Anonymous(Func):
3098    arg_types = {"this": True, "expressions": False}
3099    is_var_len_args = True
class ApproxDistinct(AggFunc):
3102class ApproxDistinct(AggFunc):
3103    arg_types = {"this": True, "accuracy": False}
class Array(Func):
3106class Array(Func):
3107    arg_types = {"expressions": False}
3108    is_var_len_args = True
class GenerateSeries(Func):
3111class GenerateSeries(Func):
3112    arg_types = {"start": True, "end": True, "step": False}
class ArrayAgg(AggFunc):
3115class ArrayAgg(AggFunc):
3116    pass
class ArrayAll(Func):
3119class ArrayAll(Func):
3120    arg_types = {"this": True, "expression": True}
class ArrayAny(Func):
3123class ArrayAny(Func):
3124    arg_types = {"this": True, "expression": True}
class ArrayConcat(Func):
3127class ArrayConcat(Func):
3128    arg_types = {"this": True, "expressions": False}
3129    is_var_len_args = True
class ArrayContains(Func):
3132class ArrayContains(Func):
3133    arg_types = {"this": True, "expression": True}
class ArrayFilter(Func):
3136class ArrayFilter(Func):
3137    arg_types = {"this": True, "expression": True}
3138    _sql_names = ["FILTER", "ARRAY_FILTER"]
class ArrayJoin(Func):
3141class ArrayJoin(Func):
3142    arg_types = {"this": True, "expression": True, "null": False}
class ArraySize(Func):
3145class ArraySize(Func):
3146    arg_types = {"this": True, "expression": False}
class ArraySort(Func):
3149class ArraySort(Func):
3150    arg_types = {"this": True, "expression": False}
class ArraySum(Func):
3153class ArraySum(Func):
3154    pass
class ArrayUnionAgg(AggFunc):
3157class ArrayUnionAgg(AggFunc):
3158    pass
class Avg(AggFunc):
3161class Avg(AggFunc):
3162    pass
class AnyValue(AggFunc):
3165class AnyValue(AggFunc):
3166    pass
class Case(Func):
3169class Case(Func):
3170    arg_types = {"this": False, "ifs": True, "default": False}
class Cast(Func):
3173class Cast(Func):
3174    arg_types = {"this": True, "to": True}
3175
3176    @property
3177    def name(self) -> str:
3178        return self.this.name
3179
3180    @property
3181    def to(self):
3182        return self.args["to"]
3183
3184    @property
3185    def output_name(self):
3186        return self.name
3187
3188    def is_type(self, dtype: DataType.Type) -> bool:
3189        return self.to.is_type(dtype)
output_name

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
def is_type(self, dtype: sqlglot.expressions.DataType.Type) -> bool:
3188    def is_type(self, dtype: DataType.Type) -> bool:
3189        return self.to.is_type(dtype)
class Collate(Binary):
3192class Collate(Binary):
3193    pass
class TryCast(Cast):
3196class TryCast(Cast):
3197    pass
class Ceil(Func):
3200class Ceil(Func):
3201    arg_types = {"this": True, "decimals": False}
3202    _sql_names = ["CEIL", "CEILING"]
class Coalesce(Func):
3205class Coalesce(Func):
3206    arg_types = {"this": True, "expressions": False}
3207    is_var_len_args = True
class Concat(Func):
3210class Concat(Func):
3211    arg_types = {"expressions": True}
3212    is_var_len_args = True
class ConcatWs(Concat):
3215class ConcatWs(Concat):
3216    _sql_names = ["CONCAT_WS"]
class Count(AggFunc):
3219class Count(AggFunc):
3220    arg_types = {"this": False}
class CurrentDate(Func):
3223class CurrentDate(Func):
3224    arg_types = {"this": False}
class CurrentDatetime(Func):
3227class CurrentDatetime(Func):
3228    arg_types = {"this": False}
class CurrentTime(Func):
3231class CurrentTime(Func):
3232    arg_types = {"this": False}
class CurrentTimestamp(Func):
3235class CurrentTimestamp(Func):
3236    arg_types = {"this": False}
class DateAdd(Func, TimeUnit):
3239class DateAdd(Func, TimeUnit):
3240    arg_types = {"this": True, "expression": True, "unit": False}
class DateSub(Func, TimeUnit):
3243class DateSub(Func, TimeUnit):
3244    arg_types = {"this": True, "expression": True, "unit": False}
class DateDiff(Func, TimeUnit):
3247class DateDiff(Func, TimeUnit):
3248    arg_types = {"this": True, "expression": True, "unit": False}
class DateTrunc(Func):
3251class DateTrunc(Func):
3252    arg_types = {"unit": True, "this": True, "zone": False}
class DatetimeAdd(Func, TimeUnit):
3255class DatetimeAdd(Func, TimeUnit):
3256    arg_types = {"this": True, "expression": True, "unit": False}
class DatetimeSub(Func, TimeUnit):
3259class DatetimeSub(Func, TimeUnit):
3260    arg_types = {"this": True, "expression": True, "unit": False}
class DatetimeDiff(Func, TimeUnit):
3263class DatetimeDiff(Func, TimeUnit):
3264    arg_types = {"this": True, "expression": True, "unit": False}
class DatetimeTrunc(Func, TimeUnit):
3267class DatetimeTrunc(Func, TimeUnit):
3268    arg_types = {"this": True, "unit": True, "zone": False}
class DayOfWeek(Func):
3271class DayOfWeek(Func):
3272    _sql_names = ["DAY_OF_WEEK", "DAYOFWEEK"]
class DayOfMonth(Func):
3275class DayOfMonth(Func):
3276    _sql_names = ["DAY_OF_MONTH", "DAYOFMONTH"]
class DayOfYear(Func):
3279class DayOfYear(Func):
3280    _sql_names = ["DAY_OF_YEAR", "DAYOFYEAR"]
class WeekOfYear(Func):
3283class WeekOfYear(Func):
3284    _sql_names = ["WEEK_OF_YEAR", "WEEKOFYEAR"]
class LastDateOfMonth(Func):
3287class LastDateOfMonth(Func):
3288    pass
class Extract(Func):
3291class Extract(Func):
3292    arg_types = {"this": True, "expression": True}
class TimestampAdd(Func, TimeUnit):
3295class TimestampAdd(Func, TimeUnit):
3296    arg_types = {"this": True, "expression": True, "unit": False}
class TimestampSub(Func, TimeUnit):
3299class TimestampSub(Func, TimeUnit):
3300    arg_types = {"this": True, "expression": True, "unit": False}
class TimestampDiff(Func, TimeUnit):
3303class TimestampDiff(Func, TimeUnit):
3304    arg_types = {"this": True, "expression": True, "unit": False}
class TimestampTrunc(Func, TimeUnit):
3307class TimestampTrunc(Func, TimeUnit):
3308    arg_types = {"this": True, "unit": True, "zone": False}
class TimeAdd(Func, TimeUnit):
3311class TimeAdd(Func, TimeUnit):
3312    arg_types = {"this": True, "expression": True, "unit": False}
class TimeSub(Func, TimeUnit):
3315class TimeSub(Func, TimeUnit):
3316    arg_types = {"this": True, "expression": True, "unit": False}
class TimeDiff(Func, TimeUnit):
3319class TimeDiff(Func, TimeUnit):
3320    arg_types = {"this": True, "expression": True, "unit": False}
class TimeTrunc(Func, TimeUnit):
3323class TimeTrunc(Func, TimeUnit):
3324    arg_types = {"this": True, "unit": True, "zone": False}
class DateFromParts(Func):
3327class DateFromParts(Func):
3328    _sql_names = ["DATEFROMPARTS"]
3329    arg_types = {"year": True, "month": True, "day": True}
class DateStrToDate(Func):
3332class DateStrToDate(Func):
3333    pass
class DateToDateStr(Func):
3336class DateToDateStr(Func):
3337    pass
class DateToDi(Func):
3340class DateToDi(Func):
3341    pass
class Day(Func):
3344class Day(Func):
3345    pass
class Decode(Func):
3348class Decode(Func):
3349    arg_types = {"this": True, "charset": True, "replace": False}
class DiToDate(Func):
3352class DiToDate(Func):
3353    pass
class Encode(Func):
3356class Encode(Func):
3357    arg_types = {"this": True, "charset": True}
class Exp(Func):
3360class Exp(Func):
3361    pass
class Explode(Func):
3364class Explode(Func):
3365    pass
class Floor(Func):
3368class Floor(Func):
3369    arg_types = {"this": True, "decimals": False}
class Greatest(Func):
3372class Greatest(Func):
3373    arg_types = {"this": True, "expressions": False}
3374    is_var_len_args = True
class GroupConcat(Func):
3377class GroupConcat(Func):
3378    arg_types = {"this": True, "separator": False}
class Hex(Func):
3381class Hex(Func):
3382    pass
class If(Func):
3385class If(Func):
3386    arg_types = {"this": True, "true": True, "false": False}
class IfNull(Func):
3389class IfNull(Func):
3390    arg_types = {"this": True, "expression": False}
3391    _sql_names = ["IFNULL", "NVL"]
class Initcap(Func):
3394class Initcap(Func):
3395    pass
class JSONBContains(Binary):
3398class JSONBContains(Binary):
3399    _sql_names = ["JSONB_CONTAINS"]
class JSONExtract(Binary, Func):
3402class JSONExtract(Binary, Func):
3403    _sql_names = ["JSON_EXTRACT"]
class JSONExtractScalar(JSONExtract):
3406class JSONExtractScalar(JSONExtract):
3407    _sql_names = ["JSON_EXTRACT_SCALAR"]
class JSONBExtract(JSONExtract):
3410class JSONBExtract(JSONExtract):
3411    _sql_names = ["JSONB_EXTRACT"]
class JSONBExtractScalar(JSONExtract):
3414class JSONBExtractScalar(JSONExtract):
3415    _sql_names = ["JSONB_EXTRACT_SCALAR"]
class Least(Func):
3418class Least(Func):
3419    arg_types = {"this": True, "expressions": False}
3420    is_var_len_args = True
class Length(Func):
3423class Length(Func):
3424    pass
class Levenshtein(Func):
3427class Levenshtein(Func):
3428    arg_types = {
3429        "this": True,
3430        "expression": False,
3431        "ins_cost": False,
3432        "del_cost": False,
3433        "sub_cost": False,
3434    }
class Ln(Func):
3437class Ln(Func):
3438    pass
class Log(Func):
3441class Log(Func):
3442    arg_types = {"this": True, "expression": False}
class Log2(Func):
3445class Log2(Func):
3446    pass
class Log10(Func):
3449class Log10(Func):
3450    pass
class LogicalOr(AggFunc):
3453class LogicalOr(AggFunc):
3454    _sql_names = ["LOGICAL_OR", "BOOL_OR"]
class Lower(Func):
3457class Lower(Func):
3458    _sql_names = ["LOWER", "LCASE"]
class Map(Func):
3461class Map(Func):
3462    arg_types = {"keys": False, "values": False}
class VarMap(Func):
3465class VarMap(Func):
3466    arg_types = {"keys": True, "values": True}
3467    is_var_len_args = True
class Matches(Func):
3470class Matches(Func):
3471    """Oracle/Snowflake decode.
3472    https://docs.oracle.com/cd/B19306_01/server.102/b14200/functions040.htm
3473    Pattern matching MATCHES(value, search1, result1, ...searchN, resultN, else)
3474    """
3475
3476    arg_types = {"this": True, "expressions": True}
3477    is_var_len_args = True

Oracle/Snowflake decode. https://docs.oracle.com/cd/B19306_01/server.102/b14200/functions040.htm Pattern matching MATCHES(value, search1, result1, ...searchN, resultN, else)

class Max(AggFunc):
3480class Max(AggFunc):
3481    arg_types = {"this": True, "expression": False}
class Min(AggFunc):
3484class Min(AggFunc):
3485    arg_types = {"this": True, "expression": False}
class Month(Func):
3488class Month(Func):
3489    pass
class Nvl2(Func):
3492class Nvl2(Func):
3493    arg_types = {"this": True, "true": True, "false": False}
class Posexplode(Func):
3496class Posexplode(Func):
3497    pass
class Pow(Binary, Func):
3500class Pow(Binary, Func):
3501    _sql_names = ["POWER", "POW"]
class PercentileCont(AggFunc):
3504class PercentileCont(AggFunc):
3505    pass
class PercentileDisc(AggFunc):
3508class PercentileDisc(AggFunc):
3509    pass
class Quantile(AggFunc):
3512class Quantile(AggFunc):
3513    arg_types = {"this": True, "quantile": True}
class Quantiles(AggFunc):
3518class Quantiles(AggFunc):
3519    arg_types = {"parameters": True, "expressions": True}
class QuantileIf(AggFunc):
3522class QuantileIf(AggFunc):
3523    arg_types = {"parameters": True, "expressions": True}
class ApproxQuantile(Quantile):
3526class ApproxQuantile(Quantile):
3527    arg_types = {"this": True, "quantile": True, "accuracy": False, "weight": False}
class RangeN(Func):
3530class RangeN(Func):
3531    arg_types = {"this": True, "expressions": True, "each": False}
class ReadCSV(Func):
3534class ReadCSV(Func):
3535    _sql_names = ["READ_CSV"]
3536    is_var_len_args = True
3537    arg_types = {"this": True, "expressions": False}
class Reduce(Func):
3540class Reduce(Func):
3541    arg_types = {"this": True, "initial": True, "merge": True, "finish": False}
class RegexpExtract(Func):
3544class RegexpExtract(Func):
3545    arg_types = {
3546        "this": True,
3547        "expression": True,
3548        "position": False,
3549        "occurrence": False,
3550        "group": False,
3551    }
class RegexpLike(Func):
3554class RegexpLike(Func):
3555    arg_types = {"this": True, "expression": True, "flag": False}
class RegexpILike(Func):
3558class RegexpILike(Func):
3559    arg_types = {"this": True, "expression": True, "flag": False}
class RegexpSplit(Func):
3562class RegexpSplit(Func):
3563    arg_types = {"this": True, "expression": True}
class Repeat(Func):
3566class Repeat(Func):
3567    arg_types = {"this": True, "times": True}
class Round(Func):
3570class Round(Func):
3571    arg_types = {"this": True, "decimals": False}
class RowNumber(Func):
3574class RowNumber(Func):
3575    arg_types: t.Dict[str, t.Any] = {}
class SafeDivide(Func):
3578class SafeDivide(Func):
3579    arg_types = {"this": True, "expression": True}
class SetAgg(AggFunc):
3582class SetAgg(AggFunc):
3583    pass
class SortArray(Func):
3586class SortArray(Func):
3587    arg_types = {"this": True, "asc": False}
class Split(Func):
3590class Split(Func):
3591    arg_types = {"this": True, "expression": True, "limit": False}
class Substring(Func):
3596class Substring(Func):
3597    arg_types = {"this": True, "start": False, "length": False}
class StrPosition(Func):
3600class StrPosition(Func):
3601    arg_types = {
3602        "this": True,
3603        "substr": True,
3604        "position": False,
3605        "instance": False,
3606    }
class StrToDate(Func):
3609class StrToDate(Func):
3610    arg_types = {"this": True, "format": True}
class StrToTime(Func):
3613class StrToTime(Func):
3614    arg_types = {"this": True, "format": True}
class StrToUnix(Func):
3619class StrToUnix(Func):
3620    arg_types = {"this": False, "format": False}
class NumberToStr(Func):
3623class NumberToStr(Func):
3624    arg_types = {"this": True, "format": True}
class Struct(Func):
3627class Struct(Func):
3628    arg_types = {"expressions": True}
3629    is_var_len_args = True
class StructExtract(Func):
3632class StructExtract(Func):
3633    arg_types = {"this": True, "expression": True}
class Sum(AggFunc):
3636class Sum(AggFunc):
3637    pass
class Sqrt(Func):
3640class Sqrt(Func):
3641    pass
class Stddev(AggFunc):
3644class Stddev(AggFunc):
3645    pass
class StddevPop(AggFunc):
3648class StddevPop(AggFunc):
3649    pass
class StddevSamp(AggFunc):
3652class StddevSamp(AggFunc):
3653    pass
class TimeToStr(Func):
3656class TimeToStr(Func):
3657    arg_types = {"this": True, "format": True}
class TimeToTimeStr(Func):
3660class TimeToTimeStr(Func):
3661    pass
class TimeToUnix(Func):
3664class TimeToUnix(Func):
3665    pass
class TimeStrToDate(Func):
3668class TimeStrToDate(Func):
3669    pass
class TimeStrToTime(Func):
3672class TimeStrToTime(Func):
3673    pass
class TimeStrToUnix(Func):
3676class TimeStrToUnix(Func):
3677    pass
class Trim(Func):
3680class Trim(Func):
3681    arg_types = {
3682        "this": True,
3683        "expression": False,
3684        "position": False,
3685        "collation": False,
3686    }
class TsOrDsAdd(Func, TimeUnit):
3689class TsOrDsAdd(Func, TimeUnit):
3690    arg_types = {"this": True, "expression": True, "unit": False}
class TsOrDsToDateStr(Func):
3693class TsOrDsToDateStr(Func):
3694    pass
class TsOrDsToDate(Func):
3697class TsOrDsToDate(Func):
3698    arg_types = {"this": True, "format": False}
class TsOrDiToDi(Func):
3701class TsOrDiToDi(Func):
3702    pass
class Unhex(Func):
3705class Unhex(Func):
3706    pass
class UnixToStr(Func):
3709class UnixToStr(Func):
3710    arg_types = {"this": True, "format": False}
class UnixToTime(Func):
3715class UnixToTime(Func):
3716    arg_types = {"this": True, "scale": False, "zone": False, "hours": False, "minutes": False}
3717
3718    SECONDS = Literal.string("seconds")
3719    MILLIS = Literal.string("millis")
3720    MICROS = Literal.string("micros")
class UnixToTimeStr(Func):
3723class UnixToTimeStr(Func):
3724    pass
class Upper(Func):
3727class Upper(Func):
3728    _sql_names = ["UPPER", "UCASE"]
class Variance(AggFunc):
3731class Variance(AggFunc):
3732    _sql_names = ["VARIANCE", "VARIANCE_SAMP", "VAR_SAMP"]
class VariancePop(AggFunc):
3735class VariancePop(AggFunc):
3736    _sql_names = ["VARIANCE_POP", "VAR_POP"]
class Week(Func):
3739class Week(Func):
3740    arg_types = {"this": True, "mode": False}
class XMLTable(Func):
3743class XMLTable(Func):
3744    arg_types = {"this": True, "passing": False, "columns": False, "by_ref": False}
class Year(Func):
3747class Year(Func):
3748    pass
class Use(Expression):
3751class Use(Expression):
3752    arg_types = {"this": True, "kind": False}
class Merge(Expression):
3755class Merge(Expression):
3756    arg_types = {"this": True, "using": True, "on": True, "expressions": True}
class When(Func):
3759class When(Func):
3760    arg_types = {"this": True, "then": True}
def maybe_parse( sql_or_expression: str | sqlglot.expressions.Expression, *, into: Union[str, Type[sqlglot.expressions.Expression], Collection[Union[str, Type[sqlglot.expressions.Expression]]], NoneType] = None, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, prefix: Optional[str] = None, copy: bool = False, **opts) -> sqlglot.expressions.Expression:
3788def maybe_parse(
3789    sql_or_expression: str | Expression,
3790    *,
3791    into: t.Optional[IntoType] = None,
3792    dialect: DialectType = None,
3793    prefix: t.Optional[str] = None,
3794    copy: bool = False,
3795    **opts,
3796) -> Expression:
3797    """Gracefully handle a possible string or expression.
3798
3799    Example:
3800        >>> maybe_parse("1")
3801        (LITERAL this: 1, is_string: False)
3802        >>> maybe_parse(to_identifier("x"))
3803        (IDENTIFIER this: x, quoted: False)
3804
3805    Args:
3806        sql_or_expression: the SQL code string or an expression
3807        into: the SQLGlot Expression to parse into
3808        dialect: the dialect used to parse the input expressions (in the case that an
3809            input expression is a SQL string).
3810        prefix: a string to prefix the sql with before it gets parsed
3811            (automatically includes a space)
3812        copy: whether or not to copy the expression.
3813        **opts: other options to use to parse the input expressions (again, in the case
3814            that an input expression is a SQL string).
3815
3816    Returns:
3817        Expression: the parsed or given expression.
3818    """
3819    if isinstance(sql_or_expression, Expression):
3820        if copy:
3821            return sql_or_expression.copy()
3822        return sql_or_expression
3823
3824    import sqlglot
3825
3826    sql = str(sql_or_expression)
3827    if prefix:
3828        sql = f"{prefix} {sql}"
3829    return sqlglot.parse_one(sql, read=dialect, into=into, **opts)

Gracefully handle a possible string or expression.

Example:
>>> maybe_parse("1")
(LITERAL this: 1, is_string: False)
>>> maybe_parse(to_identifier("x"))
(IDENTIFIER this: x, quoted: False)
Arguments:
  • sql_or_expression: the SQL code string or an expression
  • into: the SQLGlot Expression to parse into
  • dialect: the dialect used to parse the input expressions (in the case that an input expression is a SQL string).
  • prefix: a string to prefix the sql with before it gets parsed (automatically includes a space)
  • copy: whether or not to copy the expression.
  • **opts: other options to use to parse the input expressions (again, in the case that an input expression is a SQL string).
Returns:

Expression: the parsed or given expression.

def union(left, right, distinct=True, dialect=None, **opts):
3975def union(left, right, distinct=True, dialect=None, **opts):
3976    """
3977    Initializes a syntax tree from one UNION expression.
3978
3979    Example:
3980        >>> union("SELECT * FROM foo", "SELECT * FROM bla").sql()
3981        'SELECT * FROM foo UNION SELECT * FROM bla'
3982
3983    Args:
3984        left (str | Expression): the SQL code string corresponding to the left-hand side.
3985            If an `Expression` instance is passed, it will be used as-is.
3986        right (str | Expression): the SQL code string corresponding to the right-hand side.
3987            If an `Expression` instance is passed, it will be used as-is.
3988        distinct (bool): set the DISTINCT flag if and only if this is true.
3989        dialect (str): the dialect used to parse the input expression.
3990        opts (kwargs): other options to use to parse the input expressions.
3991    Returns:
3992        Union: the syntax tree for the UNION expression.
3993    """
3994    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
3995    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
3996
3997    return Union(this=left, expression=right, distinct=distinct)

Initializes a syntax tree from one UNION expression.

Example:
>>> union("SELECT * FROM foo", "SELECT * FROM bla").sql()
'SELECT * FROM foo UNION SELECT * FROM bla'
Arguments:
  • left (str | Expression): the SQL code string corresponding to the left-hand side. If an Expression instance is passed, it will be used as-is.
  • right (str | Expression): the SQL code string corresponding to the right-hand side. If an Expression instance is passed, it will be used as-is.
  • distinct (bool): set the DISTINCT flag if and only if this is true.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Union: the syntax tree for the UNION expression.

def intersect(left, right, distinct=True, dialect=None, **opts):
4000def intersect(left, right, distinct=True, dialect=None, **opts):
4001    """
4002    Initializes a syntax tree from one INTERSECT expression.
4003
4004    Example:
4005        >>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql()
4006        'SELECT * FROM foo INTERSECT SELECT * FROM bla'
4007
4008    Args:
4009        left (str | Expression): the SQL code string corresponding to the left-hand side.
4010            If an `Expression` instance is passed, it will be used as-is.
4011        right (str | Expression): the SQL code string corresponding to the right-hand side.
4012            If an `Expression` instance is passed, it will be used as-is.
4013        distinct (bool): set the DISTINCT flag if and only if this is true.
4014        dialect (str): the dialect used to parse the input expression.
4015        opts (kwargs): other options to use to parse the input expressions.
4016    Returns:
4017        Intersect: the syntax tree for the INTERSECT expression.
4018    """
4019    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
4020    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
4021
4022    return Intersect(this=left, expression=right, distinct=distinct)

Initializes a syntax tree from one INTERSECT expression.

Example:
>>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql()
'SELECT * FROM foo INTERSECT SELECT * FROM bla'
Arguments:
  • left (str | Expression): the SQL code string corresponding to the left-hand side. If an Expression instance is passed, it will be used as-is.
  • right (str | Expression): the SQL code string corresponding to the right-hand side. If an Expression instance is passed, it will be used as-is.
  • distinct (bool): set the DISTINCT flag if and only if this is true.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Intersect: the syntax tree for the INTERSECT expression.

def except_(left, right, distinct=True, dialect=None, **opts):
4025def except_(left, right, distinct=True, dialect=None, **opts):
4026    """
4027    Initializes a syntax tree from one EXCEPT expression.
4028
4029    Example:
4030        >>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql()
4031        'SELECT * FROM foo EXCEPT SELECT * FROM bla'
4032
4033    Args:
4034        left (str | Expression): the SQL code string corresponding to the left-hand side.
4035            If an `Expression` instance is passed, it will be used as-is.
4036        right (str | Expression): the SQL code string corresponding to the right-hand side.
4037            If an `Expression` instance is passed, it will be used as-is.
4038        distinct (bool): set the DISTINCT flag if and only if this is true.
4039        dialect (str): the dialect used to parse the input expression.
4040        opts (kwargs): other options to use to parse the input expressions.
4041    Returns:
4042        Except: the syntax tree for the EXCEPT statement.
4043    """
4044    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
4045    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
4046
4047    return Except(this=left, expression=right, distinct=distinct)

Initializes a syntax tree from one EXCEPT expression.

Example:
>>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql()
'SELECT * FROM foo EXCEPT SELECT * FROM bla'
Arguments:
  • left (str | Expression): the SQL code string corresponding to the left-hand side. If an Expression instance is passed, it will be used as-is.
  • right (str | Expression): the SQL code string corresponding to the right-hand side. If an Expression instance is passed, it will be used as-is.
  • distinct (bool): set the DISTINCT flag if and only if this is true.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Except: the syntax tree for the EXCEPT statement.

def select( *expressions: str | sqlglot.expressions.Expression, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts) -> sqlglot.expressions.Select:
4050def select(*expressions: str | Expression, dialect: DialectType = None, **opts) -> Select:
4051    """
4052    Initializes a syntax tree from one or multiple SELECT expressions.
4053
4054    Example:
4055        >>> select("col1", "col2").from_("tbl").sql()
4056        'SELECT col1, col2 FROM tbl'
4057
4058    Args:
4059        *expressions: the SQL code string to parse as the expressions of a
4060            SELECT statement. If an Expression instance is passed, this is used as-is.
4061        dialect: the dialect used to parse the input expressions (in the case that an
4062            input expression is a SQL string).
4063        **opts: other options to use to parse the input expressions (again, in the case
4064            that an input expression is a SQL string).
4065
4066    Returns:
4067        Select: the syntax tree for the SELECT statement.
4068    """
4069    return Select().select(*expressions, dialect=dialect, **opts)

Initializes a syntax tree from one or multiple SELECT expressions.

Example:
>>> select("col1", "col2").from_("tbl").sql()
'SELECT col1, col2 FROM tbl'
Arguments:
  • *expressions: the SQL code string to parse as the expressions of a SELECT statement. If an Expression instance is passed, this is used as-is.
  • dialect: the dialect used to parse the input expressions (in the case that an input expression is a SQL string).
  • **opts: other options to use to parse the input expressions (again, in the case that an input expression is a SQL string).
Returns:

Select: the syntax tree for the SELECT statement.

def from_(*expressions, dialect=None, **opts) -> sqlglot.expressions.Select:
4072def from_(*expressions, dialect=None, **opts) -> Select:
4073    """
4074    Initializes a syntax tree from a FROM expression.
4075
4076    Example:
4077        >>> from_("tbl").select("col1", "col2").sql()
4078        'SELECT col1, col2 FROM tbl'
4079
4080    Args:
4081        *expressions (str | Expression): the SQL code string to parse as the FROM expressions of a
4082            SELECT statement. If an Expression instance is passed, this is used as-is.
4083        dialect (str): the dialect used to parse the input expression (in the case that the
4084            input expression is a SQL string).
4085        **opts: other options to use to parse the input expressions (again, in the case
4086            that the input expression is a SQL string).
4087
4088    Returns:
4089        Select: the syntax tree for the SELECT statement.
4090    """
4091    return Select().from_(*expressions, dialect=dialect, **opts)

Initializes a syntax tree from a FROM expression.

Example:
>>> from_("tbl").select("col1", "col2").sql()
'SELECT col1, col2 FROM tbl'
Arguments:
  • *expressions (str | Expression): the SQL code string to parse as the FROM expressions of a SELECT statement. If an Expression instance is passed, this is used as-is.
  • dialect (str): the dialect used to parse the input expression (in the case that the input expression is a SQL string).
  • **opts: other options to use to parse the input expressions (again, in the case that the input expression is a SQL string).
Returns:

Select: the syntax tree for the SELECT statement.

def update( table, properties, where=None, from_=None, dialect=None, **opts) -> sqlglot.expressions.Update:
4094def update(table, properties, where=None, from_=None, dialect=None, **opts) -> Update:
4095    """
4096    Creates an update statement.
4097
4098    Example:
4099        >>> update("my_table", {"x": 1, "y": "2", "z": None}, from_="baz", where="id > 1").sql()
4100        "UPDATE my_table SET x = 1, y = '2', z = NULL FROM baz WHERE id > 1"
4101
4102    Args:
4103        *properties (Dict[str, Any]): dictionary of properties to set which are
4104            auto converted to sql objects eg None -> NULL
4105        where (str): sql conditional parsed into a WHERE statement
4106        from_ (str): sql statement parsed into a FROM statement
4107        dialect (str): the dialect used to parse the input expressions.
4108        **opts: other options to use to parse the input expressions.
4109
4110    Returns:
4111        Update: the syntax tree for the UPDATE statement.
4112    """
4113    update = Update(this=maybe_parse(table, into=Table, dialect=dialect))
4114    update.set(
4115        "expressions",
4116        [
4117            EQ(this=maybe_parse(k, dialect=dialect, **opts), expression=convert(v))
4118            for k, v in properties.items()
4119        ],
4120    )
4121    if from_:
4122        update.set(
4123            "from",
4124            maybe_parse(from_, into=From, dialect=dialect, prefix="FROM", **opts),
4125        )
4126    if isinstance(where, Condition):
4127        where = Where(this=where)
4128    if where:
4129        update.set(
4130            "where",
4131            maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts),
4132        )
4133    return update

Creates an update statement.

Example:
>>> update("my_table", {"x": 1, "y": "2", "z": None}, from_="baz", where="id > 1").sql()
"UPDATE my_table SET x = 1, y = '2', z = NULL FROM baz WHERE id > 1"
Arguments:
  • *properties (Dict[str, Any]): dictionary of properties to set which are auto converted to sql objects eg None -> NULL
  • where (str): sql conditional parsed into a WHERE statement
  • from_ (str): sql statement parsed into a FROM statement
  • dialect (str): the dialect used to parse the input expressions.
  • **opts: other options to use to parse the input expressions.
Returns:

Update: the syntax tree for the UPDATE statement.

def delete(table, where=None, dialect=None, **opts) -> sqlglot.expressions.Delete:
4136def delete(table, where=None, dialect=None, **opts) -> Delete:
4137    """
4138    Builds a delete statement.
4139
4140    Example:
4141        >>> delete("my_table", where="id > 1").sql()
4142        'DELETE FROM my_table WHERE id > 1'
4143
4144    Args:
4145        where (str|Condition): sql conditional parsed into a WHERE statement
4146        dialect (str): the dialect used to parse the input expressions.
4147        **opts: other options to use to parse the input expressions.
4148
4149    Returns:
4150        Delete: the syntax tree for the DELETE statement.
4151    """
4152    return Delete(
4153        this=maybe_parse(table, into=Table, dialect=dialect, **opts),
4154        where=Where(this=where)
4155        if isinstance(where, Condition)
4156        else maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts),
4157    )

Builds a delete statement.

Example:
>>> delete("my_table", where="id > 1").sql()
'DELETE FROM my_table WHERE id > 1'
Arguments:
  • where (str|Condition): sql conditional parsed into a WHERE statement
  • dialect (str): the dialect used to parse the input expressions.
  • **opts: other options to use to parse the input expressions.
Returns:

Delete: the syntax tree for the DELETE statement.

def condition(expression, dialect=None, **opts) -> sqlglot.expressions.Condition:
4160def condition(expression, dialect=None, **opts) -> Condition:
4161    """
4162    Initialize a logical condition expression.
4163
4164    Example:
4165        >>> condition("x=1").sql()
4166        'x = 1'
4167
4168        This is helpful for composing larger logical syntax trees:
4169        >>> where = condition("x=1")
4170        >>> where = where.and_("y=1")
4171        >>> Select().from_("tbl").select("*").where(where).sql()
4172        'SELECT * FROM tbl WHERE x = 1 AND y = 1'
4173
4174    Args:
4175        *expression (str | Expression): the SQL code string to parse.
4176            If an Expression instance is passed, this is used as-is.
4177        dialect (str): the dialect used to parse the input expression (in the case that the
4178            input expression is a SQL string).
4179        **opts: other options to use to parse the input expressions (again, in the case
4180            that the input expression is a SQL string).
4181
4182    Returns:
4183        Condition: the expression
4184    """
4185    return maybe_parse(  # type: ignore
4186        expression,
4187        into=Condition,
4188        dialect=dialect,
4189        **opts,
4190    )

Initialize a logical condition expression.

Example:
>>> condition("x=1").sql()
'x = 1'

This is helpful for composing larger logical syntax trees:

>>> where = condition("x=1")
>>> where = where.and_("y=1")
>>> Select().from_("tbl").select("*").where(where).sql()
'SELECT * FROM tbl WHERE x = 1 AND y = 1'
Arguments:
  • *expression (str | Expression): the SQL code string to parse. If an Expression instance is passed, this is used as-is.
  • dialect (str): the dialect used to parse the input expression (in the case that the input expression is a SQL string).
  • **opts: other options to use to parse the input expressions (again, in the case that the input expression is a SQL string).
Returns:

Condition: the expression

def and_(*expressions, dialect=None, **opts) -> sqlglot.expressions.And:
4193def and_(*expressions, dialect=None, **opts) -> And:
4194    """
4195    Combine multiple conditions with an AND logical operator.
4196
4197    Example:
4198        >>> and_("x=1", and_("y=1", "z=1")).sql()
4199        'x = 1 AND (y = 1 AND z = 1)'
4200
4201    Args:
4202        *expressions (str | Expression): the SQL code strings to parse.
4203            If an Expression instance is passed, this is used as-is.
4204        dialect (str): the dialect used to parse the input expression.
4205        **opts: other options to use to parse the input expressions.
4206
4207    Returns:
4208        And: the new condition
4209    """
4210    return _combine(expressions, And, dialect, **opts)

Combine multiple conditions with an AND logical operator.

Example:
>>> and_("x=1", and_("y=1", "z=1")).sql()
'x = 1 AND (y = 1 AND z = 1)'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
  • dialect (str): the dialect used to parse the input expression.
  • **opts: other options to use to parse the input expressions.
Returns:

And: the new condition

def or_(*expressions, dialect=None, **opts) -> sqlglot.expressions.Or:
4213def or_(*expressions, dialect=None, **opts) -> Or:
4214    """
4215    Combine multiple conditions with an OR logical operator.
4216
4217    Example:
4218        >>> or_("x=1", or_("y=1", "z=1")).sql()
4219        'x = 1 OR (y = 1 OR z = 1)'
4220
4221    Args:
4222        *expressions (str | Expression): the SQL code strings to parse.
4223            If an Expression instance is passed, this is used as-is.
4224        dialect (str): the dialect used to parse the input expression.
4225        **opts: other options to use to parse the input expressions.
4226
4227    Returns:
4228        Or: the new condition
4229    """
4230    return _combine(expressions, Or, dialect, **opts)

Combine multiple conditions with an OR logical operator.

Example:
>>> or_("x=1", or_("y=1", "z=1")).sql()
'x = 1 OR (y = 1 OR z = 1)'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
  • dialect (str): the dialect used to parse the input expression.
  • **opts: other options to use to parse the input expressions.
Returns:

Or: the new condition

def not_(expression, dialect=None, **opts) -> sqlglot.expressions.Not:
4233def not_(expression, dialect=None, **opts) -> Not:
4234    """
4235    Wrap a condition with a NOT operator.
4236
4237    Example:
4238        >>> not_("this_suit='black'").sql()
4239        "NOT this_suit = 'black'"
4240
4241    Args:
4242        expression (str | Expression): the SQL code strings to parse.
4243            If an Expression instance is passed, this is used as-is.
4244        dialect (str): the dialect used to parse the input expression.
4245        **opts: other options to use to parse the input expressions.
4246
4247    Returns:
4248        Not: the new condition
4249    """
4250    this = condition(
4251        expression,
4252        dialect=dialect,
4253        **opts,
4254    )
4255    return Not(this=_wrap_operator(this))

Wrap a condition with a NOT operator.

Example:
>>> not_("this_suit='black'").sql()
"NOT this_suit = 'black'"
Arguments:
  • expression (str | Expression): the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
  • dialect (str): the dialect used to parse the input expression.
  • **opts: other options to use to parse the input expressions.
Returns:

Not: the new condition

def paren(expression) -> sqlglot.expressions.Paren:
4258def paren(expression) -> Paren:
4259    return Paren(this=expression)
def to_identifier(name, quoted=None):
4275def to_identifier(name, quoted=None):
4276    """Builds an identifier.
4277
4278    Args:
4279        name: The name to turn into an identifier.
4280        quoted: Whether or not force quote the identifier.
4281
4282    Returns:
4283        The identifier ast node.
4284    """
4285
4286    if name is None:
4287        return None
4288
4289    if isinstance(name, Identifier):
4290        identifier = name
4291    elif isinstance(name, str):
4292        identifier = Identifier(
4293            this=name,
4294            quoted=not re.match(SAFE_IDENTIFIER_RE, name) if quoted is None else quoted,
4295        )
4296    else:
4297        raise ValueError(f"Name needs to be a string or an Identifier, got: {name.__class__}")
4298    return identifier

Builds an identifier.

Arguments:
  • name: The name to turn into an identifier.
  • quoted: Whether or not force quote the identifier.
Returns:

The identifier ast node.

def to_interval( interval: str | sqlglot.expressions.Literal) -> sqlglot.expressions.Interval:
4304def to_interval(interval: str | Literal) -> Interval:
4305    """Builds an interval expression from a string like '1 day' or '5 months'."""
4306    if isinstance(interval, Literal):
4307        if not interval.is_string:
4308            raise ValueError("Invalid interval string.")
4309
4310        interval = interval.this
4311
4312    interval_parts = INTERVAL_STRING_RE.match(interval)  # type: ignore
4313
4314    if not interval_parts:
4315        raise ValueError("Invalid interval string.")
4316
4317    return Interval(
4318        this=Literal.string(interval_parts.group(1)),
4319        unit=Var(this=interval_parts.group(2)),
4320    )

Builds an interval expression from a string like '1 day' or '5 months'.

def to_table( sql_path: Union[str, sqlglot.expressions.Table, NoneType], **kwargs) -> Optional[sqlglot.expressions.Table]:
4333def to_table(sql_path: t.Optional[str | Table], **kwargs) -> t.Optional[Table]:
4334    """
4335    Create a table expression from a `[catalog].[schema].[table]` sql path. Catalog and schema are optional.
4336    If a table is passed in then that table is returned.
4337
4338    Args:
4339        sql_path: a `[catalog].[schema].[table]` string.
4340
4341    Returns:
4342        A table expression.
4343    """
4344    if sql_path is None or isinstance(sql_path, Table):
4345        return sql_path
4346    if not isinstance(sql_path, str):
4347        raise ValueError(f"Invalid type provided for a table: {type(sql_path)}")
4348
4349    catalog, db, table_name = (to_identifier(x) for x in split_num_words(sql_path, ".", 3))
4350    return Table(this=table_name, db=db, catalog=catalog, **kwargs)

Create a table expression from a [catalog].[schema].[table] sql path. Catalog and schema are optional. If a table is passed in then that table is returned.

Arguments:
  • sql_path: a [catalog].[schema].[table] string.
Returns:

A table expression.

def to_column( sql_path: str | sqlglot.expressions.Column, **kwargs) -> sqlglot.expressions.Column:
4353def to_column(sql_path: str | Column, **kwargs) -> Column:
4354    """
4355    Create a column from a `[table].[column]` sql path. Schema is optional.
4356
4357    If a column is passed in then that column is returned.
4358
4359    Args:
4360        sql_path: `[table].[column]` string
4361    Returns:
4362        Table: A column expression
4363    """
4364    if sql_path is None or isinstance(sql_path, Column):
4365        return sql_path
4366    if not isinstance(sql_path, str):
4367        raise ValueError(f"Invalid type provided for column: {type(sql_path)}")
4368    table_name, column_name = (to_identifier(x) for x in split_num_words(sql_path, ".", 2))
4369    return Column(this=column_name, table=table_name, **kwargs)

Create a column from a [table].[column] sql path. Schema is optional.

If a column is passed in then that column is returned.

Arguments:
  • sql_path: [table].[column] string
Returns:

Table: A column expression

def alias_( expression: str | sqlglot.expressions.Expression, alias: str | sqlglot.expressions.Identifier, table: Union[bool, Sequence[str | sqlglot.expressions.Identifier]] = False, quoted: Optional[bool] = None, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts):
4372def alias_(
4373    expression: str | Expression,
4374    alias: str | Identifier,
4375    table: bool | t.Sequence[str | Identifier] = False,
4376    quoted: t.Optional[bool] = None,
4377    dialect: DialectType = None,
4378    **opts,
4379):
4380    """Create an Alias expression.
4381
4382    Example:
4383        >>> alias_('foo', 'bar').sql()
4384        'foo AS bar'
4385
4386        >>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql()
4387        '(SELECT 1, 2) AS bar(a, b)'
4388
4389    Args:
4390        expression: the SQL code strings to parse.
4391            If an Expression instance is passed, this is used as-is.
4392        alias: the alias name to use. If the name has
4393            special characters it is quoted.
4394        table: Whether or not to create a table alias, can also be a list of columns.
4395        quoted: whether or not to quote the alias
4396        dialect: the dialect used to parse the input expression.
4397        **opts: other options to use to parse the input expressions.
4398
4399    Returns:
4400        Alias: the aliased expression
4401    """
4402    exp = maybe_parse(expression, dialect=dialect, **opts)
4403    alias = to_identifier(alias, quoted=quoted)
4404
4405    if table:
4406        table_alias = TableAlias(this=alias)
4407        exp.set("alias", table_alias)
4408
4409        if not isinstance(table, bool):
4410            for column in table:
4411                table_alias.append("columns", to_identifier(column, quoted=quoted))
4412
4413        return exp
4414
4415    # We don't set the "alias" arg for Window expressions, because that would add an IDENTIFIER node in
4416    # the AST, representing a "named_window" [1] construct (eg. bigquery). What we want is an ALIAS node
4417    # for the complete Window expression.
4418    #
4419    # [1]: https://cloud.google.com/bigquery/docs/reference/standard-sql/window-function-calls
4420
4421    if "alias" in exp.arg_types and not isinstance(exp, Window):
4422        exp = exp.copy()
4423        exp.set("alias", alias)
4424        return exp
4425    return Alias(this=exp, alias=alias)

Create an Alias expression.

Example:
>>> alias_('foo', 'bar').sql()
'foo AS bar'
>>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql()
'(SELECT 1, 2) AS bar(a, b)'
Arguments:
  • expression: the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
  • alias: the alias name to use. If the name has special characters it is quoted.
  • table: Whether or not to create a table alias, can also be a list of columns.
  • quoted: whether or not to quote the alias
  • dialect: the dialect used to parse the input expression.
  • **opts: other options to use to parse the input expressions.
Returns:

Alias: the aliased expression

def subquery(expression, alias=None, dialect=None, **opts):
4428def subquery(expression, alias=None, dialect=None, **opts):
4429    """
4430    Build a subquery expression.
4431
4432    Example:
4433        >>> subquery('select x from tbl', 'bar').select('x').sql()
4434        'SELECT x FROM (SELECT x FROM tbl) AS bar'
4435
4436    Args:
4437        expression (str | Expression): the SQL code strings to parse.
4438            If an Expression instance is passed, this is used as-is.
4439        alias (str | Expression): the alias name to use.
4440        dialect (str): the dialect used to parse the input expression.
4441        **opts: other options to use to parse the input expressions.
4442
4443    Returns:
4444        Select: a new select with the subquery expression included
4445    """
4446
4447    expression = maybe_parse(expression, dialect=dialect, **opts).subquery(alias)
4448    return Select().from_(expression, dialect=dialect, **opts)

Build a subquery expression.

Example:
>>> subquery('select x from tbl', 'bar').select('x').sql()
'SELECT x FROM (SELECT x FROM tbl) AS bar'
Arguments:
  • expression (str | Expression): the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
  • alias (str | Expression): the alias name to use.
  • dialect (str): the dialect used to parse the input expression.
  • **opts: other options to use to parse the input expressions.
Returns:

Select: a new select with the subquery expression included

def column( col: str | sqlglot.expressions.Identifier, table: Union[str, sqlglot.expressions.Identifier, NoneType] = None, schema: Union[str, sqlglot.expressions.Identifier, NoneType] = None, quoted: Optional[bool] = None) -> sqlglot.expressions.Column:
4451def column(
4452    col: str | Identifier,
4453    table: t.Optional[str | Identifier] = None,
4454    schema: t.Optional[str | Identifier] = None,
4455    quoted: t.Optional[bool] = None,
4456) -> Column:
4457    """
4458    Build a Column.
4459
4460    Args:
4461        col: column name
4462        table: table name
4463        schema: schema name
4464        quoted: whether or not to force quote each part
4465    Returns:
4466        Column: column instance
4467    """
4468    return Column(
4469        this=to_identifier(col, quoted=quoted),
4470        table=to_identifier(table, quoted=quoted),
4471        schema=to_identifier(schema, quoted=quoted),
4472    )

Build a Column.

Arguments:
  • col: column name
  • table: table name
  • schema: schema name
  • quoted: whether or not to force quote each part
Returns:

Column: column instance

4475def cast(expression: str | Expression, to: str | DataType | DataType.Type, **opts) -> Cast:
4476    """Cast an expression to a data type.
4477
4478    Example:
4479        >>> cast('x + 1', 'int').sql()
4480        'CAST(x + 1 AS INT)'
4481
4482    Args:
4483        expression: The expression to cast.
4484        to: The datatype to cast to.
4485
4486    Returns:
4487        A cast node.
4488    """
4489    expression = maybe_parse(expression, **opts)
4490    return Cast(this=expression, to=DataType.build(to, **opts))

Cast an expression to a data type.

Example:
>>> cast('x + 1', 'int').sql()
'CAST(x + 1 AS INT)'
Arguments:
  • expression: The expression to cast.
  • to: The datatype to cast to.
Returns:

A cast node.

def table_( table, db=None, catalog=None, quoted=None, alias=None) -> sqlglot.expressions.Table:
4493def table_(table, db=None, catalog=None, quoted=None, alias=None) -> Table:
4494    """Build a Table.
4495
4496    Args:
4497        table (str | Expression): column name
4498        db (str | Expression): db name
4499        catalog (str | Expression): catalog name
4500
4501    Returns:
4502        Table: table instance
4503    """
4504    return Table(
4505        this=to_identifier(table, quoted=quoted),
4506        db=to_identifier(db, quoted=quoted),
4507        catalog=to_identifier(catalog, quoted=quoted),
4508        alias=TableAlias(this=to_identifier(alias)) if alias else None,
4509    )

Build a Table.

Arguments:
  • table (str | Expression): column name
  • db (str | Expression): db name
  • catalog (str | Expression): catalog name
Returns:

Table: table instance

def values( values: Iterable[Tuple[Any, ...]], alias: Optional[str] = None, columns: Union[Iterable[str], Dict[str, sqlglot.expressions.DataType], NoneType] = None) -> sqlglot.expressions.Values:
4512def values(
4513    values: t.Iterable[t.Tuple[t.Any, ...]],
4514    alias: t.Optional[str] = None,
4515    columns: t.Optional[t.Iterable[str] | t.Dict[str, DataType]] = None,
4516) -> Values:
4517    """Build VALUES statement.
4518
4519    Example:
4520        >>> values([(1, '2')]).sql()
4521        "VALUES (1, '2')"
4522
4523    Args:
4524        values: values statements that will be converted to SQL
4525        alias: optional alias
4526        columns: Optional list of ordered column names or ordered dictionary of column names to types.
4527         If either are provided then an alias is also required.
4528         If a dictionary is provided then the first column of the values will be casted to the expected type
4529         in order to help with type inference.
4530
4531    Returns:
4532        Values: the Values expression object
4533    """
4534    if columns and not alias:
4535        raise ValueError("Alias is required when providing columns")
4536    table_alias = (
4537        TableAlias(this=to_identifier(alias), columns=[to_identifier(x) for x in columns])
4538        if columns
4539        else TableAlias(this=to_identifier(alias) if alias else None)
4540    )
4541    expressions = [convert(tup) for tup in values]
4542    if columns and isinstance(columns, dict):
4543        types = list(columns.values())
4544        expressions[0].set(
4545            "expressions",
4546            [cast(x, types[i]) for i, x in enumerate(expressions[0].expressions)],
4547        )
4548    return Values(
4549        expressions=expressions,
4550        alias=table_alias,
4551    )

Build VALUES statement.

Example:
>>> values([(1, '2')]).sql()
"VALUES (1, '2')"
Arguments:
  • values: values statements that will be converted to SQL
  • alias: optional alias
  • columns: Optional list of ordered column names or ordered dictionary of column names to types. If either are provided then an alias is also required. If a dictionary is provided then the first column of the values will be casted to the expected type in order to help with type inference.
Returns:

Values: the Values expression object

def var( name: Union[str, sqlglot.expressions.Expression, NoneType]) -> sqlglot.expressions.Var:
4554def var(name: t.Optional[str | Expression]) -> Var:
4555    """Build a SQL variable.
4556
4557    Example:
4558        >>> repr(var('x'))
4559        '(VAR this: x)'
4560
4561        >>> repr(var(column('x', table='y')))
4562        '(VAR this: x)'
4563
4564    Args:
4565        name: The name of the var or an expression who's name will become the var.
4566
4567    Returns:
4568        The new variable node.
4569    """
4570    if not name:
4571        raise ValueError(f"Cannot convert empty name into var.")
4572
4573    if isinstance(name, Expression):
4574        name = name.name
4575    return Var(this=name)

Build a SQL variable.

Example:
>>> repr(var('x'))
'(VAR this: x)'
>>> repr(var(column('x', table='y')))
'(VAR this: x)'
Arguments:
  • name: The name of the var or an expression who's name will become the var.
Returns:

The new variable node.

def rename_table( old_name: str | sqlglot.expressions.Table, new_name: str | sqlglot.expressions.Table) -> sqlglot.expressions.AlterTable:
4578def rename_table(old_name: str | Table, new_name: str | Table) -> AlterTable:
4579    """Build ALTER TABLE... RENAME... expression
4580
4581    Args:
4582        old_name: The old name of the table
4583        new_name: The new name of the table
4584
4585    Returns:
4586        Alter table expression
4587    """
4588    old_table = to_table(old_name)
4589    new_table = to_table(new_name)
4590    return AlterTable(
4591        this=old_table,
4592        actions=[
4593            RenameTable(this=new_table),
4594        ],
4595    )

Build ALTER TABLE... RENAME... expression

Arguments:
  • old_name: The old name of the table
  • new_name: The new name of the table
Returns:

Alter table expression

def convert(value) -> sqlglot.expressions.Expression:
4598def convert(value) -> Expression:
4599    """Convert a python value into an expression object.
4600
4601    Raises an error if a conversion is not possible.
4602
4603    Args:
4604        value (Any): a python object
4605
4606    Returns:
4607        Expression: the equivalent expression object
4608    """
4609    if isinstance(value, Expression):
4610        return value
4611    if value is None:
4612        return NULL
4613    if isinstance(value, bool):
4614        return Boolean(this=value)
4615    if isinstance(value, str):
4616        return Literal.string(value)
4617    if isinstance(value, float) and math.isnan(value):
4618        return NULL
4619    if isinstance(value, numbers.Number):
4620        return Literal.number(value)
4621    if isinstance(value, tuple):
4622        return Tuple(expressions=[convert(v) for v in value])
4623    if isinstance(value, list):
4624        return Array(expressions=[convert(v) for v in value])
4625    if isinstance(value, dict):
4626        return Map(
4627            keys=[convert(k) for k in value],
4628            values=[convert(v) for v in value.values()],
4629        )
4630    if isinstance(value, datetime.datetime):
4631        datetime_literal = Literal.string(
4632            (value if value.tzinfo else value.replace(tzinfo=datetime.timezone.utc)).isoformat()
4633        )
4634        return TimeStrToTime(this=datetime_literal)
4635    if isinstance(value, datetime.date):
4636        date_literal = Literal.string(value.strftime("%Y-%m-%d"))
4637        return DateStrToDate(this=date_literal)
4638    raise ValueError(f"Cannot convert {value}")

Convert a python value into an expression object.

Raises an error if a conversion is not possible.

Arguments:
  • value (Any): a python object
Returns:

Expression: the equivalent expression object

def replace_children(expression, fun):
4641def replace_children(expression, fun):
4642    """
4643    Replace children of an expression with the result of a lambda fun(child) -> exp.
4644    """
4645    for k, v in expression.args.items():
4646        is_list_arg = isinstance(v, list)
4647
4648        child_nodes = v if is_list_arg else [v]
4649        new_child_nodes = []
4650
4651        for cn in child_nodes:
4652            if isinstance(cn, Expression):
4653                for child_node in ensure_collection(fun(cn)):
4654                    new_child_nodes.append(child_node)
4655                    child_node.parent = expression
4656                    child_node.arg_key = k
4657            else:
4658                new_child_nodes.append(cn)
4659
4660        expression.args[k] = new_child_nodes if is_list_arg else seq_get(new_child_nodes, 0)

Replace children of an expression with the result of a lambda fun(child) -> exp.

def column_table_names(expression):
4663def column_table_names(expression):
4664    """
4665    Return all table names referenced through columns in an expression.
4666
4667    Example:
4668        >>> import sqlglot
4669        >>> column_table_names(sqlglot.parse_one("a.b AND c.d AND c.e"))
4670        ['c', 'a']
4671
4672    Args:
4673        expression (sqlglot.Expression): expression to find table names
4674
4675    Returns:
4676        list: A list of unique names
4677    """
4678    return list(dict.fromkeys(column.table for column in expression.find_all(Column)))

Return all table names referenced through columns in an expression.

Example:
>>> import sqlglot
>>> column_table_names(sqlglot.parse_one("a.b AND c.d AND c.e"))
['c', 'a']
Arguments:
  • expression (sqlglot.Expression): expression to find table names
Returns:

list: A list of unique names

def table_name(table) -> str:
4681def table_name(table) -> str:
4682    """Get the full name of a table as a string.
4683
4684    Args:
4685        table (exp.Table | str): table expression node or string.
4686
4687    Examples:
4688        >>> from sqlglot import exp, parse_one
4689        >>> table_name(parse_one("select * from a.b.c").find(exp.Table))
4690        'a.b.c'
4691
4692    Returns:
4693        The table name.
4694    """
4695
4696    table = maybe_parse(table, into=Table)
4697
4698    if not table:
4699        raise ValueError(f"Cannot parse {table}")
4700
4701    return ".".join(
4702        part
4703        for part in (
4704            table.text("catalog"),
4705            table.text("db"),
4706            table.name,
4707        )
4708        if part
4709    )

Get the full name of a table as a string.

Arguments:
  • table (exp.Table | str): table expression node or string.
Examples:
>>> from sqlglot import exp, parse_one
>>> table_name(parse_one("select * from a.b.c").find(exp.Table))
'a.b.c'
Returns:

The table name.

def replace_tables(expression, mapping):
4712def replace_tables(expression, mapping):
4713    """Replace all tables in expression according to the mapping.
4714
4715    Args:
4716        expression (sqlglot.Expression): expression node to be transformed and replaced.
4717        mapping (Dict[str, str]): mapping of table names.
4718
4719    Examples:
4720        >>> from sqlglot import exp, parse_one
4721        >>> replace_tables(parse_one("select * from a.b"), {"a.b": "c"}).sql()
4722        'SELECT * FROM c'
4723
4724    Returns:
4725        The mapped expression.
4726    """
4727
4728    def _replace_tables(node):
4729        if isinstance(node, Table):
4730            new_name = mapping.get(table_name(node))
4731            if new_name:
4732                return to_table(
4733                    new_name,
4734                    **{k: v for k, v in node.args.items() if k not in ("this", "db", "catalog")},
4735                )
4736        return node
4737
4738    return expression.transform(_replace_tables)

Replace all tables in expression according to the mapping.

Arguments:
  • expression (sqlglot.Expression): expression node to be transformed and replaced.
  • mapping (Dict[str, str]): mapping of table names.
Examples:
>>> from sqlglot import exp, parse_one
>>> replace_tables(parse_one("select * from a.b"), {"a.b": "c"}).sql()
'SELECT * FROM c'
Returns:

The mapped expression.

def replace_placeholders(expression, *args, **kwargs):
4741def replace_placeholders(expression, *args, **kwargs):
4742    """Replace placeholders in an expression.
4743
4744    Args:
4745        expression (sqlglot.Expression): expression node to be transformed and replaced.
4746        args: positional names that will substitute unnamed placeholders in the given order.
4747        kwargs: keyword arguments that will substitute named placeholders.
4748
4749    Examples:
4750        >>> from sqlglot import exp, parse_one
4751        >>> replace_placeholders(
4752        ...     parse_one("select * from :tbl where ? = ?"), "a", "b", tbl="foo"
4753        ... ).sql()
4754        'SELECT * FROM foo WHERE a = b'
4755
4756    Returns:
4757        The mapped expression.
4758    """
4759
4760    def _replace_placeholders(node, args, **kwargs):
4761        if isinstance(node, Placeholder):
4762            if node.name:
4763                new_name = kwargs.get(node.name)
4764                if new_name:
4765                    return to_identifier(new_name)
4766            else:
4767                try:
4768                    return to_identifier(next(args))
4769                except StopIteration:
4770                    pass
4771        return node
4772
4773    return expression.transform(_replace_placeholders, iter(args), **kwargs)

Replace placeholders in an expression.

Arguments:
  • expression (sqlglot.Expression): expression node to be transformed and replaced.
  • args: positional names that will substitute unnamed placeholders in the given order.
  • kwargs: keyword arguments that will substitute named placeholders.
Examples:
>>> from sqlglot import exp, parse_one
>>> replace_placeholders(
...     parse_one("select * from :tbl where ? = ?"), "a", "b", tbl="foo"
... ).sql()
'SELECT * FROM foo WHERE a = b'
Returns:

The mapped expression.

def expand( expression: sqlglot.expressions.Expression, sources: Dict[str, sqlglot.expressions.Subqueryable], copy=True) -> sqlglot.expressions.Expression:
4776def expand(expression: Expression, sources: t.Dict[str, Subqueryable], copy=True) -> Expression:
4777    """Transforms an expression by expanding all referenced sources into subqueries.
4778
4779    Examples:
4780        >>> from sqlglot import parse_one
4781        >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y")}).sql()
4782        'SELECT * FROM (SELECT * FROM y) AS z /* source: x */'
4783
4784    Args:
4785        expression: The expression to expand.
4786        sources: A dictionary of name to Subqueryables.
4787        copy: Whether or not to copy the expression during transformation. Defaults to True.
4788
4789    Returns:
4790        The transformed expression.
4791    """
4792
4793    def _expand(node: Expression):
4794        if isinstance(node, Table):
4795            name = table_name(node)
4796            source = sources.get(name)
4797            if source:
4798                subquery = source.subquery(node.alias or name)
4799                subquery.comments = [f"source: {name}"]
4800                return subquery
4801        return node
4802
4803    return expression.transform(_expand, copy=copy)

Transforms an expression by expanding all referenced sources into subqueries.

Examples:
>>> from sqlglot import parse_one
>>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y")}).sql()
'SELECT * FROM (SELECT * FROM y) AS z /* source: x */'
Arguments:
  • expression: The expression to expand.
  • sources: A dictionary of name to Subqueryables.
  • copy: Whether or not to copy the expression during transformation. Defaults to True.
Returns:

The transformed expression.

def func( name: str, *args, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **kwargs) -> sqlglot.expressions.Func:
4806def func(name: str, *args, dialect: DialectType = None, **kwargs) -> Func:
4807    """
4808    Returns a Func expression.
4809
4810    Examples:
4811        >>> func("abs", 5).sql()
4812        'ABS(5)'
4813
4814        >>> func("cast", this=5, to=DataType.build("DOUBLE")).sql()
4815        'CAST(5 AS DOUBLE)'
4816
4817    Args:
4818        name: the name of the function to build.
4819        args: the args used to instantiate the function of interest.
4820        dialect: the source dialect.
4821        kwargs: the kwargs used to instantiate the function of interest.
4822
4823    Note:
4824        The arguments `args` and `kwargs` are mutually exclusive.
4825
4826    Returns:
4827        An instance of the function of interest, or an anonymous function, if `name` doesn't
4828        correspond to an existing `sqlglot.expressions.Func` class.
4829    """
4830    if args and kwargs:
4831        raise ValueError("Can't use both args and kwargs to instantiate a function.")
4832
4833    from sqlglot.dialects.dialect import Dialect
4834
4835    args = tuple(convert(arg) for arg in args)
4836    kwargs = {key: convert(value) for key, value in kwargs.items()}
4837
4838    parser = Dialect.get_or_raise(dialect)().parser()
4839    from_args_list = parser.FUNCTIONS.get(name.upper())
4840
4841    if from_args_list:
4842        function = from_args_list(args) if args else from_args_list.__self__(**kwargs)  # type: ignore
4843    else:
4844        kwargs = kwargs or {"expressions": args}
4845        function = Anonymous(this=name, **kwargs)
4846
4847    for error_message in function.error_messages(args):
4848        raise ValueError(error_message)
4849
4850    return function

Returns a Func expression.

Examples:
>>> func("abs", 5).sql()
'ABS(5)'
>>> func("cast", this=5, to=DataType.build("DOUBLE")).sql()
'CAST(5 AS DOUBLE)'
Arguments:
  • name: the name of the function to build.
  • args: the args used to instantiate the function of interest.
  • dialect: the source dialect.
  • kwargs: the kwargs used to instantiate the function of interest.
Note:

The arguments args and kwargs are mutually exclusive.

Returns:

An instance of the function of interest, or an anonymous function, if name doesn't correspond to an existing sqlglot.expressions.Func class.

def true():
4853def true():
4854    """
4855    Returns a true Boolean expression.
4856    """
4857    return Boolean(this=True)

Returns a true Boolean expression.

def false():
4860def false():
4861    """
4862    Returns a false Boolean expression.
4863    """
4864    return Boolean(this=False)

Returns a false Boolean expression.

def null():
4867def null():
4868    """
4869    Returns a Null expression.
4870    """
4871    return Null()

Returns a Null expression.